Step-up authentication

You can set up multi-factor authentication to work in one of two models:

• Strict, where secured operations always require the highest Authenticator Assurance Level (AAL).
• Lax, where the secured operations require only the aal1 Authenticator Assurance Level (AAL).

In Ory Network, the default multi-factor authentication enforcement model is Strict. This means that high-risk operations via self-service endpoints, such as updating user settings, require step-up authentication by default.

You can set the required authentication model for these operations/endpoints:

• User sign-in (getting an Ory Session) / /sessions/whoami endpoint
• Self-service user settings

Configuration

Ory Console

To change the multi-factor authentication enforcement to Lax and allow users to sign in or access user settings without authenticating with the second factor, go to Authentication → Two-factor auth in the Ory Console and use the switches in the General Settings section.

https://console.ory.sh/

Ory CLI

Follow these steps to adjust the settings in the Ory Network using the Ory CLI:

1. Get the Ory Identities configuration from your project and save it to a file:

   ## List all available workspaces
   ory list workspaces
   
   ## List all available projects
   ory list projects --workspace <workspace-id>
   
   ## Get config
   ory get identity-config --project <project-id> --workspace <workspace-id> --format yaml > identity-config.yaml

2. Adjust the values of the indicated keys to the desired values:

   identity-config.yaml

   # ...
   selfservice:
     flows:
       settings:
         required_aal: highest_available
   # ...
   session:
     whoami:
       required_aal: highest_available
   # ...
   tip

   Use aal1 for the Lax model and highest_available for the Strict model. The default value in Ory Network is highest_available.

3. Update the Ory Identities configuration using the file you worked with:

   ory update identity-config --project <project-id> --workspace <workspace-id> --file identity-config.yaml

Trigger Dynamic Multi-Factor authentication

To protect your application's sensitive functions - like accessing payment details, an order history, or private content - you can make users complete a second authentication factor in their current session by initiating a new login flow using one of these endpoints with the aal parameter set to aal2:

• /self-service/login/browser
• /self-service/login/api

For example:

/self-service/login/browser?aal=aal2
/self-service/login/api?aal=aal2

note

If the Ory Session has aal2 already, this will error. In that case, you can request to refresh the session using the second factor:

/self-service/login/browser?refresh=true&aal=aal2
/self-service/login/api?refresh=true&aal=aal2

When the user successfully provides their configured second factor:

• The method, for example totp, is added to the Ory Session.
• Ory Session Authenticator Assurance Level (AAL) is set to aal2.
• The authenticated_at time is set to the time when the user provides the second factor.