Getting started with step-up authentication

To add another layer of app security, we are happy to introduce Frontegg's Step-up Authentication. Step-up acts as a digital guardian for your app and adds a security step where a user undergoes additional identity verification before trying to access restricted areas, complete sensitive actions (e.g., payment), or perform permission-specific activities in your app.

Step-up SDKs

Go to the relevant tech stack to implement Step Up Authentication. Note that versioning is important to be able to use the feature.

Client side

React

Client side

Angular

Client side

vue

Client side

Vanilla.js

When should users be Stepped-up?

While multifactor authentication has been a common practice for a while, you may wonder when a user might need to re-verify their identity— in addition to their initial authentication. Let's list some common use cases. Examples include:

1. Inviting external users to join the app/to access restricted areas, or before any action in your app that requires permissions associated with a specific role.
2. Users opting to perform payment-related actions (e.g., checkout page).
3. In case unusual traffic is detected, it is a best practice to ensure that no malignant activity is happening.

Important values for user step-up

Note regarding amr and acr values:

To enroll user to perform a step-up, Frontegg considers the amr and acr values in the JWT to decide whether a user needs to authenticate or not. Note that refresh tokens do not include the amr and acr, so users will always need to re-authenticate before the step-up operation.

To get a user to Step-up, frontegg takes into account the following core claims, all included within the user's ID Token (JWT):

acr – the Authentication Context Reference (ACR). Frontegg supports the following acr for multi-factor authentication, represented as http://schemas.openid.net/pape/policies/2007/06/multi-factor, for reference see the OpenID spec.

amr – the Authentication Method Reference (AMR), describing how the user was authenticated. If the user is enrolled in Multi-Factor Authentication (MFA), this field will include an mfa to signal that's how they were stepped up, along with the authentication method that was used, e.g., One Time Password (OTP).

auth_time – The time duration that has passed since the user was last authenticated. If exceeded, the user will need to re-authenticate before being stepped-up.

{
  "acr": "http://schemas.openid.net/pape/policies/2007/06/multi-factor",
  "amr": [
    "mfa",
    "otp"
  ],
  "auth_time": 170350725
}

JWT max_age

Users need to be authenticated before being stepped up. If you set a max_age parameter to your JWT (in seconds), users will need to re-authenticate if they've passed this timeframe (calculated according to the JWT's auth_time claim). Please refer to the relevant SDK for more details.

The flow

Let's showcase the user's flow via the use-case of a checkout page.

When a user proceeds to make a payment, they will be asked to re-verify their identity (i.e., to Step-up) before they provide sensitive payment information. At this point, Frontegg's step-up flow will differ slightly whether you are a Frontegg Hosted or Embedded Login user:

Hosted login

• For hosted login users, Frontegg will check if the user's ID token contains the acr(Authorization Context Reference) necessary to enroll them in a Step-up flow, and if their associated auth_time claim is valid and not expired.

• If the auth_time didn't exceed the maximum, the user will be requested to verify their identity via Step-up Authentication. If not— they will be redirected to login again before initiating the Step-up stage.

• After the user re-authenticates, they'll be redirected to the application, and their JWT will now include the http://schemas.openid.net/pape/policies/2007/06/multi-factor as their acr alongside the relevant auth_time claim.

Embedded login

• For embedded login users, Frontegg will check if the user's ID token contains the acr and that theirauth_time` claim is valid.

• If the user's auth_time has expired, the user will be redirected to /[APP_URL]/account/re-authenticate?...&acr_values=[requested-acr] to re-authenticate.

• After the user re-authenticates, they'll be redirected to the application, and their JWT will now include http://schemas.openid.net/pape/policies/2007/06/multi-factor as their acr along the relevant auth_time claim.

Choosing which MFA to display

Currently, Frontegg supports MFA as the only Authentication Context Reference (acr), displayed in the JWT as http://schemas.openid.net/pape/policies/2007/06/multi-factor. If the user has no MFA configured (Learn more about MFA, they will receive an email with a One-Time-Password (OTP) as a verification method. If using MFA during the step-up stage, the type of MFA used will be returned on the amr (Authentication Method Reference) claim in the user's JWT.

Please note the following instances:

• If the user has NO MFA associated with their account AND they DID NOT log in with a MagicLink / MagicCode, then they will receive an OTP (6 digits email challenge) to re-verify their identity. The amr value in the JWT will be displayed as [mfa, otp].

• If the user has NO MFA associated with their account and logged in with a MagicLink/ MagicCode, they cannot receive an OTP via email. For that use-case, need to set the unenrolledmfapolicy to either ALLOW_SKIP (in which case the backend will return a stepped-up JWT) or alternatively set it to FORCE_ENROLL (in which case the user will get an error message).

• If the user has one method configured for their MFA authentication, the challenge displayed will correspond with the configured MFA (see below). The user will still have the option to either authenticate via the configured method or receive an OTP sent to their email. The amr value in the JWT will be according to the matching MFA (see table below).

• If the user has more than one MFA method associated, their available options will be listed in their authentication box, as follows:

MFA JWT indication

The table below lists the representation of the different MFA methods in the JWT: