Step-up Authentication
Frontegg's Step-up allows you to enroll users in additional authentication step to re-verify their identity before performing security-sensitive actions
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.
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:
- 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.
- Users opting to perform payment-related actions (e.g., checkout page).
- 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
andacr
valuesTo enroll user to perform a step-up, Frontegg considers the
amr
andacr
values in the JWT to decide whether a user needs to authenticate or not. Note that refresh tokens do not include theamr
andacr
, 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.
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
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 associatedauth_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 theiracr
alongside the relevantauth_time
claim.
Embedded login
- For embedded login users, Frontegg will check if the user's ID token
contains the
acrand that their
auth_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 theiracr
along the relevantauth_time
claim.
Authentication
Note that the user has to have valid authentication before they are being 'stepped-up'. Re-authentication before step up will depend on when the user was last authenticated (based on their
auth_time
) and if the time that has passed since authentication hasn't exceeded the JWT'smax_age
.
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 eitherALLOW_SKIP
(in which case the backend will return a stepped-up JWT) or alternatively set it toFORCE_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:
Authentication with an OTP
Note that users can always have the option to use OTP as a verification method— whether additional MFA options are available or not.
MFA JWT Indication
The table below lists the representation of the different MFA methods in the JWT:
Type | JWT indication |
---|---|
Email OTP | [mfa, otp] |
SMS | [mfa, sms] |
Authenticator app | [mfa, otp] |
WebAuthN (key) | [mfa, hwk] |
WebAuthN (platform) | [mfa, hwk] |
User doesn't complete MFA
If the user canceled their authentication or didn't match with any MFA criteria, the JWT will be returned without the
acr_values
claim.
Updated 9 months ago