Skip to main content

Configure multi-factor authentication in Ory Kratos

Enforce MFA​

When working with self-hosted instances of the Ory Identities (Kratos), change the enforcement model by adjusting the configuration file.

config.yml
# ...
selfservice:
  flows:
    settings:
      required_aal: highest_available
# ...
session:
  whoami:
    required_aal: aal1
# ...

This configuration forces users to provide the highest authentication factor to access their account settings. For example, users without a second factor configured can access the settings after they sign in with their password. Users that have a second factor set up (such as a TOTP app) will must complete the second factor challenge to access account settings.

It will also allow users to use your application without completing a second factor.

If instead, you want all users that configured a second factor to complete the factor before using your app, set session.whoami.required_all to highest_available.

WebAuthn​

To configure WebAuthn in your self-hosted Kratos instance, add the webauthn method to selfservice.methods in the Ory Kratos configuration file:

kratos.config.yml
selfservice:
  methods:
    webauthn:
      config:
        passwordless: false
        rp:
          display_name: SAMPLE_NAME
          # Set 'id' to the top-level domain.
          id: loginpage.com
          # Set 'origin' to the exact URL of the page that prompts the user to use WebAuthn. You must include the scheme, host, and port.
          origin: https://loginpage.auth.com:4455
      enabled: true
note

Pay special attention to the origin URL, as it has to match the scheme, host, and port of the page you're starting the flow from.

Time-based one-time passwords (TOTP)​

To configure TOTP in your self-hosted Kratos instance, add the totp method to selfservice/methods in the configuration file:

kratos.config.yml
selfservice:
  methods:
    totp:
      config:
        # The "issuer" is the name in the TOTP application users see when getting a one-time password.
        issuer: ExampleIssuerForSelfHosted.com
      enabled: true

Lookup Secrets (Recovery Codes)​

To configure lookup secrets, add the lookup_secret method to selfservice/methods in the configuration file:

kratos.config.yml
selfservice:
  methods:
    lookup_secret:
      enabled: true