Step up auth
This is a paid feature.
For self hosted users, Sign up to get a license key and follow the instructions sent to you by email. Using the dev license key is free. We only start charging you once you enable the feature in production using the provided production license key.
For managed service users, you can click on the "enable paid features" button on our dashboard, and follow the steps from there on. Once enabled, this feature is free on the provided development environment.
Step up auth is when you want the user to complete an auth challenge before navigating to a page, or before doing an action on a page.
SuperTokens allows you to implement step up auth using the following factors:
- TOTP
- Password (available only for custom UI)
- Email / SMS OTP
You can implement these as full page navigations, or as popups on the current page.
If you are using OAuth2 in your configuration, step up authentication is not supported at the moment.
Step 1. Adding backend validators
To protect sensitive APIs with step up auth, you need to check that the user has completed the required auth challenge within a certain amount of time. If they haven't, you should return a 403 to the frontend which highlights which factor is required. The frontend can then consume this and show the auth challenge to the user.
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import express from "express";
import { SessionRequest } from "supertokens-node/framework/express";
import MultiFactorAuth from "supertokens-node/recipe/multifactorauth";
import { Error as STError } from "supertokens-node/recipe/session"
let app = express();
app.post(
"/update-blog",
verifySession(),
async (req: SessionRequest, res) => {
let mfaClaim = await req.session!.getClaimValue(MultiFactorAuth.MultiFactorAuthClaim);
const totpCompletedTime = mfaClaim!.c[MultiFactorAuth.FactorIds.TOTP];
if (totpCompletedTime === undefined || totpCompletedTime < (Date.now() - 1000*60*5)) {
// this means that the user had completed the TOTP challenge more than 5 minutes ago
// so we should ask them to complete it again
throw new STError({
type: "INVALID_CLAIMS",
message: "User has not finished TOTP",
payload: [{
id: MultiFactorAuth.MultiFactorAuthClaim.key,
reason: {
message: "Factor validation failed: totp not completed",
factorId: MultiFactorAuth.FactorIds.TOTP,
},
}]
})
}
// continue with API logic...
}
);
- When calling the
verifySession, SuperTokens makes sure that the session is valid and that the user has completed all the requreied auth factors at some point in time. This enforces the basic check that the user has finished MFA during login. - We then further check that if the user has finished the TOTP login method within the last 5 mins. If they haven't, we send back a 403 to the frontend for the frontend to handle.
- You can check other factor types in this was as well. For example, if you want to check that the user has done email OTP in the last 5 mins, you can use the factor ID of
otp-email, or if you want to check that the user has entered their account password in the last 5 mins, you can checkemailpasswordfactor ID. - If users have different login methods, and / or different MFA configurations, you may want to first check what factor applies to them. You can check their login method by fetching the user object using the
getUserfunction from our SDK, and then matching thesession.getRecipeId()to the login methods in the user object. As per the MFA factors, you can see which ones are enabled for this user by using theMultiFactorAuth.getRequiredSecondaryFactorsForUserfunction. For performance reasons, you may want to put this information in the session's access token payload of the user in thecreateNewSessionoverride function of the session recipe.
Step 2. Preventing factor setup during step up auth
By default, SuperTokens allows a factor setup (for example, creating a new TOTP device), as long as the user has a session and has completed all the MFA factors required during login. This opens up a security issue when it comes to completing step up auth. Consider the following scenario:
- The user has logged in and completed TOTP
- After 5 mins, the user tries to do a sensitive action and the API for that fails with a 403 (cause of the check in step 1, above).
- The user is shown the TOTP challenge on the frontend. However, instead of completing that, they call the create TOTP device API which would succeed and then use the new TOTP device to complete the factor challenge required for the API.
This allows someome malicious to bypass step up auth. In order to prevent this, we need to override one fo the MFA recipe functions on the backend to enforce that the factor setup can only happen if the user is not in a step up auth state:
import supertokens from "supertokens-node";
import MultiFactorAuth from "supertokens-node/recipe/multifactorauth"
import { Error as STError } from "supertokens-node/recipe/session"
supertokens.init({
supertokens: {
connectionURI: "..."
},
appInfo: {
appName: "...",
apiDomain: "...",
websiteDomain: "..."
},
recipeList: [
MultiFactorAuth.init({
firstFactors: [/*...*/],
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
assertAllowedToSetupFactorElseThrowInvalidClaimError: async (input) => {
await originalImplementation.assertAllowedToSetupFactorElseThrowInvalidClaimError(input);
let claimValue = await input.session.getClaimValue(MultiFactorAuth.MultiFactorAuthClaim);
if (claimValue === undefined || !claimValue.v) {
return
}
// if the above did not throw, it means that the user has logged in and has completed all the required
// factors for login. So now we check specifically for the step up auth case:
if (input.factorId === MultiFactorAuth.FactorIds.TOTP && (await input.factorsSetUpForUser).includes(MultiFactorAuth.FactorIds.TOTP)) {
// this is an example of checking for totp, but you can also use other factor IDs.
const totpCompletedTime = claimValue.c[MultiFactorAuth.FactorIds.TOTP];
if (totpCompletedTime === undefined || totpCompletedTime < (Date.now() - 1000 * 60 * 5)) {
// this means that the user had completed the TOTP challenge more than 5 minutes ago
// so we should ask them to complete it again
throw new STError({
type: "INVALID_CLAIMS",
message: "User has not finished TOTP",
payload: [{
id: MultiFactorAuth.MultiFactorAuthClaim.key,
reason: {
message: "Factor validation failed: totp not completed",
factorId: MultiFactorAuth.FactorIds.TOTP,
},
}]
})
}
}
}
}
}
}
})
]
})
- The function
assertAllowedToSetupFactorElseThrowInvalidClaimErroris called by SuperTokens whenever the client calls an API to setup a new factor (for example, create a new TOTP device). So we do our checks in this function and throw an error in case we have to to prevent factor setup. - In the override logic, we first call the original implementation and check that the
vvalue in the MFA session claim istrue. This will throw / exit the function early in case the user has not completely logged in yet (for example, they have finished the first factor, but not the required second factor). - Then we check if the user has TOTP already setup for them, if they haven't, then we allow the factor setup (otherwise the user would not be able to complete the step up auth challenge). If they have, we do the same check we did in step 1 - checking if the user has finished TOTP in the last 5 mins or not. If they haven't, we disallow factor setup.
The customisation above prevents the security issue highlighted in the beginning of this step.
Step 3. Handling 403 on the frontend
The JSON body of the step up auth claim failure will look like this:
{
"message": "invalid claim",
"claimValidationErrors": [
{
"id": "st-mfa",
"reason": {
"message": "Factor validation failed: totp not completed",
"factorId": "totp",
}
}
]
}
What type of UI are you using?
You can check for this structure and the factorId to decide what factor to show on the frontend. You have two options to show the UI to the user:
Full page redirect to the factor
To redirect the user to as factor challenge page and then navigate them back to the current page, you can use the following function:
import MultiFactorAuth from 'supertokens-auth-react/recipe/multifactorauth';
async function redirectToTotpSetupScreen() {
MultiFactorAuth.redirectToFactor({
factorId: "totp",
stepUp: true,
redirectBack: true,
})
}
- In the snippet above, we redirect to the TOTP factor setup screen. We set the
stepUpargument totrueotherwise the MFA screen would detect that the user has already completed basic MFA requirements and would not show the verification screen. TheredirectBackargument is set totruesince we want to redirect back to the current page after the user has finished setting up the device. - You can also just redirect the user to
/{websiteBasePath}/mfa/totp?setup=true&redirectToPath={currentPath}if you don't want to use the above function.
Show the factor in a popup
Checkout the docs for embedding the pre built UI factor components in a page / popup:
Step 4. Checking for step up auth on page navigation
Sometimes, you may want to ask users to complete step up auth before displaying a page on the frontend. This is a different scenario that the above steps cause here, you do not want to reply on an API call to fail, instead you want to check for the step up auth condition before rendering the page itself.
To do this, we read the access token payload on the frontend and check the completed time of the factor we care about before rendering the page. If the completed time is older than 5 mins (as an example), we should redirect the user to the factor challenge page.
import React from "react";
import { SessionAuth, useClaimValue } from 'supertokens-auth-react/recipe/session';
import MultiFactorAuth from "supertokens-auth-react/recipe/multifactorauth";
import { DateProviderReference } from "supertokens-auth-react/utils/dateProvider"
const VerifiedRoute = (props: React.PropsWithChildren<any>) => {
return (
<SessionAuth>
<InvalidClaimHandler>
{props.children}
</InvalidClaimHandler>
</SessionAuth>
);
}
function InvalidClaimHandler(props: React.PropsWithChildren<any>) {
let claimValue = useClaimValue(MultiFactorAuth.MultiFactorAuthClaim);
if (claimValue.loading) {
return null;
}
let totpCompletedTime = claimValue.value?.c[MultiFactorAuth.FactorIds.TOTP]
if (totpCompletedTime === undefined || totpCompletedTime < (DateProviderReference.getReferenceOrThrow().dateProvider.now() - 1000 * 60 * 5)) {
return <div>You need to complete TOTP before seeing this page. Please <a href={"/auth/mfa/totp?stepUp=true&redirectToPath=" + window.location.pathname}>click here</a> to finish to proceed.</div>
}
// the user has finished TOTP, so we can render the children
return <div>{props.children}</div>;
}
- We check if the user has completed TOTP within the last 5 mins or not. If not, we show a message to the user, and ask them to complete TOTP.
- Notice that we use a
DateProviderReferenceclass exported by SuperTokens instead of just doingDate.now(). This is done to take into account any clock skew that may exist between the frontend and the backend server.