Add Step-Up Authentication With the Two-Factor APIs
On this page
This guide adds a step-up challenge before a sensitive action in your application. The example is a banking application that requires a step-up before a transfer, but not when the user views a balance. For how FusionAuth decides when to require a step-up, and how long a step-up lasts, see Step-Up Authentication.
Prerequisites#
- FusionAuth
1.62.0or later, for thePOSTmethod of the MFA Status API. - A FusionAuth API key with access to the
/api/two-factorand/api/two-factor/loginendpoints. For more information, see API Keys. - At least one MFA method enabled on the Tenant. Without one, the MFA Status API never requires a step-up.
- A server-side session in your application that stores the logged in user's Id.
The steps below send codes by email. Sending codes through FusionAuth requires the Starter plan or higher. On any plan, you can deliver codes through your own channel instead.
The following diagram shows the flow:
Step-up flow for a bank transfer with an email code.
Check Whether a Step-Up Is Required#
When the user starts a sensitive action, call the MFA Status API with an action of stepUp. Put details about the action in eventInfo.data, so an MFA Requirement Lambda can read them:
API_KEY=...
REQUEST_PAYLOAD='{...}'
curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/status' -d "$REQUEST_PAYLOAD"
{
"action": "stepUp",
"applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
"eventInfo": {
"data": {
"amount": 5000,
"operation": "transfer"
},
"ipAddress": "192.168.1.42"
},
"userId": "429797ba-37d7-4bbe-8748-58fb812448ff"
}When the API returns 200, skip the remaining steps and complete the action. When the API returns 242, continue to the next step.
Skip Low-Risk Actions With a Lambda#
This feature requires an Enterprise plan.
When some actions don't need a step-up, add an MFA Requirement Lambda to the Tenant. The following lambda skips the step-up for transfers under 100, and requires a step-up for everything else:
function checkRequired(result, user, registration, context) {
if (context.action !== 'stepUp') {
return;
}
var data = (context.eventInfo && context.eventInfo.data) || {};
if (data.operation === 'transfer' && data.amount < 100) {
result.required = false;
}
}
The lambda returns early for the login and changePassword actions, so login MFA keeps the Tenant and Application policies.
Start the Step-Up#
Call the Start Multi-Factor API:
API_KEY=...
REQUEST_PAYLOAD='{...}'
curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/start' -d "$REQUEST_PAYLOAD"
{
"applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
"state": {
"transactionId": "9f6a1c2e-3b7d-4e8a-a1f0-5c2d8e4b7a90"
},
"trustChallenge": "a1d9e8f6b2c34e7f9a0b5c6d7e8f9a0b1c2d3e4f",
"userId": "429797ba-37d7-4bbe-8748-58fb812448ff"
}Set the request fields as follows:
- Put an identifier for the pending action in
state, such as a transaction Id. FusionAuth returnsstatewhen the step-up completes, so your application can match the step-up to the action. - When your application needs the trust tokenA short-lived token that proves a user completed multi-factor authentication. Some API requests, such as changing a password when multi-factor authentication is enabled, require the token. for the Change Password API, set
trustChallengeto a long random value. The trust token then only works with the same challenge. For more information, see Trust Tokens and Trust Challenges. - When you deliver the code through your own channel, set
codeto your own value, or omitcodeand read the generated code from the response.
{
"code": "123456",
"methods": [
{
"id": "BD5R",
"method": "authenticator",
"name": "Bitwarden Authenticator",
"authenticator": {
"algorithm": "HmacSHA1",
"codeLength": 6,
"timeStep": 30
}
},
{
"id": "KLRT",
"method": "email",
"name": "Work email",
"email": "richard@piedpiper.com",
"lastUsed": true
},
{
"id": "K8RT",
"method": "email",
"name": "Personal email",
"email": "dinesh@piedpiper.com"
},
{
"id": "87KW",
"method": "sms",
"name": "Mobile",
"mobilePhone": "+13035551212"
}
],
"twoFactorId": "DvnAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}Store the twoFactorId in the user's server-side session. The twoFactorId expires after the Tenant's Two-Factor duration, five minutes by default. A new start request for the same user and Application cancels the previous twoFactorId.
Show the user the list of methods and ask the user to choose one. When methods is empty, the user has no MFA methods. Deliver the code through your own channel instead, and skip the next step.
Send the Code#
When the user chooses an authenticator method, skip this step. The user reads the code from the authenticator app.
When the user chooses an email or sms method, call the Send API with the method's id as methodId. The Send API needs no API key:
REQUEST_PAYLOAD='{...}'
TWO_FACTOR_ID=... # from the start response
curl -XPOST -H 'Content-type: application/json' 'https://local.fusionauth.io/api/two-factor/send?twoFactorId='$TWO_FACTOR_ID -d "$REQUEST_PAYLOAD"
{
"methodId": "KLRT"
}The Send API replaces the code from the start request with a new code. Don't call the Send API when you deliver your own code.
Complete the Step-Up#
Build a page that collects the code. Then call the Complete Multi-Factor Authentication API with the code and the twoFactorId. Set noJWT to true, unless your application needs new tokens. Without noJWT, FusionAuth issues a new access token and refresh token for every step-up:
API_KEY=...
REQUEST_PAYLOAD='{...}'
curl -XPOST -H 'Content-type: application/json' -H "Authorization: $API_KEY" 'https://local.fusionauth.io/api/two-factor/login' -d "$REQUEST_PAYLOAD"
{
"applicationId": "85a03867-dccf-4882-adde-1a79aeec50df",
"code": "915187",
"ipAddress": "192.168.1.42",
"noJWT": true,
"twoFactorId": "YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4"
}The API returns one of the following status codes:
200when the code is valid. The response includes the user, thestateobject, and atrustToken.421when the code is wrong. Ask the user to try again. Failed codes count toward Account Lockout.404when thetwoFactorIdhas expired or was already used. Start a new step-up.409when the account is locked. Cancel the action.
For the full list of status codes, see the Complete Multi-Factor Authentication API.
{
"state": {
"transactionId": "9f6a1c2e-3b7d-4e8a-a1f0-5c2d8e4b7a90"
},
"trustToken": "BIjOQVzvVR2Zp6hlRRwnPg1-DlTqSLsTm1W1pmYpzmQ",
"user": {
"active": true,
"email": "richard@piedpiper.com",
"id": "429797ba-37d7-4bbe-8748-58fb812448ff",
"lastLoginInstant": 1795017776252,
"twoFactor": {
"methods": [
{
"email": "richard@piedpiper.com",
"id": "KLRT",
"method": "email"
}
]
},
"verified": true
}
}Complete the Sensitive Action#
Before you complete the action, check the following in your application:
- The
user.idin the response matches the user in the server-side session. - The
statein the response matches the pending action, such as the transaction Id. - When you allow a step-up to last for a window of time, record the time of the step-up in the server-side session.
Then complete the sensitive action.
Confirm the Result#
To confirm the step-up works, test the following cases:
- Start a sensitive action and enter the correct code. The action completes.
- Start a sensitive action and enter a wrong code. The API returns
421, and the action doesn't complete. - Start a sensitive action, wait longer than the Two-Factor duration, and enter the code. The API returns
404. - When you use an MFA Requirement Lambda, start a low-risk action. The MFA Status API returns
200, and the user sees no challenge.
Related
Learn about step-up authentication in FusionAuth, including how to choose an approach and how long a step-up stays valid.
Learn about the APIs for enabling and disabling multi-factor authentication for users.
API documentation for the FusionAuth Send a Multi-Factor Code During Login or Step Up API.
API documentation for the FusionAuth Start Multi-Factor API.