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_aal 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