Skip to main content
Which UI do you use?
Custom UI
Pre built UI
Paid Feature

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

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.

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["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: "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 check emailpassword factor 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 getUser function from our SDK, and then matching the session.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 the MultiFactorAuth.getRequiredSecondaryFactorsForUser function. For performance reasons, you may want to put this information in the session's access token payload of the user in the createNewSession override 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 === "totp" && (await input.factorsSetUpForUser).includes("totp")) {
                                // this is an example of checking for totp, but you can also use other factor IDs.
                                const totpCompletedTime = claimValue.c["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: "totp",
                                            },
                                        }]
                                    })
                                }
                            }
                        }
                    }
                }
            }
        })
    ]
})
  • The function assertAllowedToSetupFactorElseThrowInvalidClaimError is 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 v value in the MFA session claim is true. 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",
      }
    }
  ]
}

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("totp", false, true)
}
  • In the snippet above, we redirect to the TOTP factor setup screen. The second argument represents a boolean for forceSetup which we set to false since we do not want to ask the user to create a new device. The third arg is also true since 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?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["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?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 DateProviderReference class exported by SuperTokens instead of just doing Date.now(). This is done to take into account any clock skew that may exist between the frontend and the backend server.
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI