Skip to main content

OTP for specific users

important

Before reading the below, please first go through the setup for OTP for all users to understand the basics of how MFA with OTP works, and then come back here.

This page shows how to implement an MFA policy that requires certain users to do the OTP challenge via email or SMS. You can decide which users based on any criteria. For example:

  • Only users that have an admin role require to do OTP; OR
  • Only users that have enabled OTP on their account require to do OTP; OR
  • Only users that have a paid account require to do OTP.

Whatever the criteria is, the steps to implementing this type of a flow is the same.

note

Assume that the first factor is email password or social login, but the same set of steps applies to other first factor types as well.

Single tenant setup​

Backend setup​

Example 1: Only enable OTP for users that have an admin role​

To start with, configure the backend in the following way:

import supertokens, { User, RecipeUserId, } from "supertokens-node";
import { UserContext } from "supertokens-node/types";
import ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import MultiFactorAuth from "supertokens-node/recipe/multifactorauth"
import Passwordless from "supertokens-node/recipe/passwordless"
import Session from "supertokens-node/recipe/session"
import UserRoles from "supertokens-node/recipe/userroles"
import AccountLinking from "supertokens-node/recipe/accountlinking"
import { AccountInfoWithRecipeId } from "supertokens-node/recipe/accountlinking/types";
import { SessionContainerInterface } from "supertokens-node/recipe/session/types";

supertokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init(),
        UserRoles.init(),
        ThirdParty.init({
            //...
        }),
        EmailPassword.init({
            //...
        }),
        Passwordless.init({
            contactMethod: "EMAIL",
            flowType: "USER_INPUT_CODE"
        }),
        AccountLinking.init({
            shouldDoAutomaticAccountLinking: async (newAccountInfo: AccountInfoWithRecipeId & { recipeUserId?: RecipeUserId }, user: User | undefined, session: SessionContainerInterface | undefined, tenantId: string, userContext: UserContext) => {
                if (session === undefined) {
                    // we do not want to do first factor account linking by default. To enable that,
                    // please see the automatic account linking docs in the recipe docs for your first factor.
                    return {
                        shouldAutomaticallyLink: false
                    };
                }
                if (user === undefined || session.getUserId() === user.id) {
                    // if it comes here, it means that a session exists, and we are trying to link the 
                    // newAccountInfo to the session user, which means it's an MFA flow, so we enable 
                    // linking here.
                    return {
                        shouldAutomaticallyLink: true,
                        shouldRequireVerification: false
                    }
                }
                return {
                    shouldAutomaticallyLink: false
                };
            }
        }),
        MultiFactorAuth.init({
            firstFactors: [
                MultiFactorAuth.FactorIds.EMAILPASSWORD,
                MultiFactorAuth.FactorIds.THIRDPARTY
            ],
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        getMFARequirementsForAuth: async function (input) {
                            let roles = await UserRoles.getRolesForUser(input.tenantId, (await input.user).id)
                            if (roles.roles.includes("admin")) {
                                // we only want otp-email for admins
                                return [MultiFactorAuth.FactorIds.OTP_EMAIL]
                            } else {
                                // no MFA for non admin users.
                                return []
                            }
                        }
                    }
                }
            }
        })
    ]
})

Override the getMFARequirementsForAuth function to indicate that otp-email applies only to users with the admin role. You can also have any other criteria here.

Example 2: Ask for OTP only for users that have enabled OTP on their account​

To start with, configure the backend in the following way:

import supertokens, { User, RecipeUserId, } from "supertokens-node";
import { UserContext } from "supertokens-node/types";
import ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import MultiFactorAuth, { MultiFactorAuthClaim } from "supertokens-node/recipe/multifactorauth"
import Passwordless from "supertokens-node/recipe/passwordless"
import Session from "supertokens-node/recipe/session"
import AccountLinking from "supertokens-node/recipe/accountlinking"
import { AccountInfoWithRecipeId } from "supertokens-node/recipe/accountlinking/types";
import { SessionContainerInterface } from "supertokens-node/recipe/session/types";

supertokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init(),
        ThirdParty.init({
            //...
        }),
        EmailPassword.init({
            //...
        }),
        Passwordless.init({
            contactMethod: "EMAIL",
            flowType: "USER_INPUT_CODE",
            override: {
                apis: (oI) => {
                    return {
                        ...oI,
                        consumeCodePOST: async function (input) {
                            let response = await oI.consumeCodePOST!(input);
                            if (response.status === "OK" && input.session !== undefined) {
                                // We do this only if a session exists, which means that it's not being called for first factor login.
                                
                                // OTP challenge completed successfully. We save that this user has enabled otp-email in the user metadata.
                                // The multifactorauth recipe will pick this value up next time the user is trying to login, and
                                // ask them to enter the OTP code.
                                await MultiFactorAuth.addToRequiredSecondaryFactorsForUser(input.session.getUserId(), MultiFactorAuth.FactorIds.OTP_EMAIL);
                            }
                            return response;
                        }
                    }
                }
            }
        }),
        AccountLinking.init({
            shouldDoAutomaticAccountLinking: async (newAccountInfo: AccountInfoWithRecipeId & { recipeUserId?: RecipeUserId }, user: User | undefined, session: SessionContainerInterface | undefined, tenantId: string, userContext: UserContext) => {
                if (session === undefined) {
                    // we do not want to do first factor account linking by default. To enable that,
                    // please see the automatic account linking docs in the recipe docs for your first factor.
                    return {
                        shouldAutomaticallyLink: false
                    };
                }
                if (user === undefined || session.getUserId() === user.id) {
                    // if it comes here, it means that a session exists, and we are trying to link the 
                    // newAccountInfo to the session user, which means it's an MFA flow, so we enable 
                    // linking here.
                    return {
                        shouldAutomaticallyLink: true,
                        shouldRequireVerification: false
                    }
                }
                return {
                    shouldAutomaticallyLink: false
                };
            }
        }),
        MultiFactorAuth.init({
            firstFactors: [
                MultiFactorAuth.FactorIds.EMAILPASSWORD,
                MultiFactorAuth.FactorIds.THIRDPARTY
            ]
        })
    ]
})
  • Initialize the multi-factor auth recipe here without any override to getMFARequirementsForAuth. The default implementation of this function already checks what factors a user has enabled and returns those. All that is needed is to mark otp-email as enabled for a user as soon as they have completed the OTP challenge successfully. This happens in the consumeCodePOST API override as shown above. Once the code is consumed successfully, mark the otp-email factor as enabled for the user, and the next time they login, they will be asked to complete the OTP challenge.
  • Notice that before calling addToRequiredSecondaryFactorsForUser, check if there is an input session or not. Only call addToRequiredSecondaryFactorsForUser function if there is a session which indicates that the user has finished some first factor already.

In both of the examples above, notice that the Passwordless recipe initializes in the recipeList. In this example, only email-based OTP is enabled, set the contactMethod to EMAIL and flowType to USER_INPUT_CODE (that is, OTP). If instead, you want to use phone SMS-based OTP, set the contact method to PHONE. If you want to give users both options, or for some users use email, and for others use phone, set contactMethod to EMAIL_OR_PHONE.

We have also enabled the account linking feature since it's required for MFA to work. The above enables account linking for second factor only, but if you also want to enable it for first factor, see this section.

Notice that shouldRequireVerification: false configures account linking. It means that the second factor can link to the first factor even though the first factor is not verified. If you want to do email verification of the first factor before setting up the second factor (for example if the first factor is email password, and the second is phone OTP), then set this boolean to true, and also init the email verification recipe on the frontend and backend in REQUIRED mode.

Once the user finishes the first factor (for example, with emailpassword), their session access token payload looks like this (for those that require OTP):

{
    "st-mfa": {
        "c": {
            "emailpassword": 1702877939,
        },
        "v": false
    }
}

The v being false indicates that there are still factors that are pending. After the user has finished otp-email, the payload looks like:

{
    "st-mfa": {
        "c": {
            "emailpassword": 1702877939,
            "otp-email": 1702877999
        },
        "v": true
    }
}

Indicating that the user has finished all required factors, and should access the app.

caution

If you are already using Passwordless or ThirdPartyPasswordless in your app as a first factor, you do not need to explicitly initialize the Passwordless recipe again.

Frontend setup​

This consists of two parts:

  • Configuring the frontend to show the OTP challenge UI when required during login / sign up
  • Allowing users to enable / disable OTP challenge on their account via the settings page (If you are following Example 2 from above).

The first part is identical to the steps mentioned in this section, please follow that.

The second part, which is only applicable in case you want to allow users to enable / disable OTP themselves, can be done by creating the following flow on your frontend:

  • When the user navigates to their settings page, you can show them if OTP challenge is active or not.
  • If enabled, you can allow them to disable it, or vice versa.

To know if the user has enabled OTP, you can make an API your backend which calls the following function:

import MultiFactorAuth from "supertokens-node/recipe/multifactorauth";

async function isOTPEmailEnabledForUser(userId: string) {
    let factors = await MultiFactorAuth.getRequiredSecondaryFactorsForUser(userId)
    return factors.includes(MultiFactorAuth.FactorIds.OTP_EMAIL)
}

If the user wants to enable or disable otp-email for them, you can make an API on your backend which calls the following function:

import MultiFactorAuth from "supertokens-node/recipe/multifactorauth";

async function enableMFAForUser(userId: string) {
    await MultiFactorAuth.addToRequiredSecondaryFactorsForUser(userId, MultiFactorAuth.FactorIds.OTP_EMAIL)
}

async function disableMFAForUser(userId: string) {
    await MultiFactorAuth.removeFromRequiredSecondaryFactorsForUser(userId, MultiFactorAuth.FactorIds.OTP_EMAIL)
}
note

If instead you want to work with otp-phone, you can replace otp-email with otp-phone in the above snippets. Also make sure that the contactMethod configures to PHONE in the Passwordless recipe on the frontend (for pre-built UI) and backend.

Multi tenant setup​

Backend setup​

A user can be a part of multiple tenants. If you want OTP to be active for a specific user across all the tenants that they are a part of, the steps are the same as in the Backend setup section above.

However, if you want OTP to be active for a specific user, for a specific tenant (or a subset of tenants that the user is a part of), then additional logic must be added to the getMFARequirementsForAuth function override. Modifying the example code from the Backend setup section above:

Example 1: Only enable OTP for users that have an admin role​

import supertokens, { User, RecipeUserId, } from "supertokens-node";
import { UserContext } from "supertokens-node/types";
import ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"

import MultiFactorAuth from "supertokens-node/recipe/multifactorauth"
import Passwordless from "supertokens-node/recipe/passwordless"
import Session from "supertokens-node/recipe/session"
import UserRoles from "supertokens-node/recipe/userroles"
import AccountLinking from "supertokens-node/recipe/accountlinking"
import { AccountInfoWithRecipeId } from "supertokens-node/recipe/accountlinking/types";
import { SessionContainerInterface } from "supertokens-node/recipe/session/types";

supertokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init(),
        UserRoles.init(),
        ThirdParty.init({
            //...
        }),
        EmailPassword.init({
            //...
        }),
        Passwordless.init({
            contactMethod: "EMAIL",
            flowType: "USER_INPUT_CODE"
        }),
        AccountLinking.init({
            shouldDoAutomaticAccountLinking: async (newAccountInfo: AccountInfoWithRecipeId & { recipeUserId?: RecipeUserId }, user: User | undefined, session: SessionContainerInterface | undefined, tenantId: string, userContext: UserContext) => {
                if (session === undefined) {
                    // we do not want to do first factor account linking by default. To enable that,
                    // please see the automatic account linking docs in the recipe docs for your first factor.
                    return {
                        shouldAutomaticallyLink: false
                    };
                }
                if (user === undefined || session.getUserId() === user.id) {
                    // if it comes here, it means that a session exists, and we are trying to link the 
                    // newAccountInfo to the session user, which means it's an MFA flow, so we enable 
                    // linking here.
                    return {
                        shouldAutomaticallyLink: true,
                        shouldRequireVerification: false
                    }
                }
                return {
                    shouldAutomaticallyLink: false
                };
            }
        }),
        MultiFactorAuth.init({
            firstFactors: [
                MultiFactorAuth.FactorIds.EMAILPASSWORD,
                MultiFactorAuth.FactorIds.THIRDPARTY
            ],
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        getMFARequirementsForAuth: async function (input) {
                            let roles = await UserRoles.getRolesForUser(input.tenantId, (await input.user).id)
                            if (roles.roles.includes("admin") && (await input.requiredSecondaryFactorsForTenant).includes(MultiFactorAuth.FactorIds.OTP_EMAIL)) {
                                // we only want otp-email for admins
                                return [MultiFactorAuth.FactorIds.OTP_EMAIL]
                            } else {
                                // no MFA for non admin users.
                                return []
                            }
                        }
                    }
                }
            }
        })
    ]
})
  • The implementation of shouldRequireOTPEmailForTenant is entirely up to you.

Example 2: Ask for OTP only for users that have enabled OTP on their account​

import supertokens, { User, RecipeUserId, } from "supertokens-node";
import { UserContext } from "supertokens-node/types";
import ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import MultiFactorAuth, { MultiFactorAuthClaim } from "supertokens-node/recipe/multifactorauth"
import Passwordless from "supertokens-node/recipe/passwordless"
import Session from "supertokens-node/recipe/session"
import AccountLinking from "supertokens-node/recipe/accountlinking"
import { AccountInfoWithRecipeId } from "supertokens-node/recipe/accountlinking/types";
import { SessionContainerInterface } from "supertokens-node/recipe/session/types";

supertokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        appName: "...",
        apiDomain: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init(),
        ThirdParty.init({
            //...
        }),
        EmailPassword.init({
            //...
        }),
        Passwordless.init({
            contactMethod: "EMAIL",
            flowType: "USER_INPUT_CODE",
            override: {
                apis: (oI) => {
                    return {
                        ...oI,
                        consumeCodePOST: async function (input) {
                            let response = await oI.consumeCodePOST!(input);
                            if (response.status === "OK" && input.session !== undefined) {
                                // We do this only if a session exists, which means that it's not being called for first factor login.
                                
                                // OTP challenge completed successfully. We save that this user has enabled otp-email in the user metadata.
                                // The multifactorauth recipe will pick this value up next time the user is trying to login, and
                                // ask them to enter the OTP code.
                                await MultiFactorAuth.addToRequiredSecondaryFactorsForUser(input.session.getUserId(), MultiFactorAuth.FactorIds.OTP_EMAIL);
                            }
                            return response;
                        }
                    }
                }
            }
        }),
        AccountLinking.init({
            shouldDoAutomaticAccountLinking: async (newAccountInfo: AccountInfoWithRecipeId & { recipeUserId?: RecipeUserId }, user: User | undefined, session: SessionContainerInterface | undefined, tenantId: string, userContext: UserContext) => {
                if (session === undefined) {
                    // we do not want to do first factor account linking by default. To enable that,
                    // please see the automatic account linking docs in the recipe docs for your first factor.
                    return {
                        shouldAutomaticallyLink: false
                    };
                }
                if (user === undefined || session.getUserId() === user.id) {
                    // if it comes here, it means that a session exists, and we are trying to link the 
                    // newAccountInfo to the session user, which means it's an MFA flow, so we enable 
                    // linking here.
                    return {
                        shouldAutomaticallyLink: true,
                        shouldRequireVerification: false
                    }
                }
                return {
                    shouldAutomaticallyLink: false
                };
            }
        }),
        MultiFactorAuth.init({
            firstFactors: [
                MultiFactorAuth.FactorIds.EMAILPASSWORD,
                MultiFactorAuth.FactorIds.THIRDPARTY
            ],
            override: {
                functions: (originalImplementation) => {
                    return {
                        ...originalImplementation,
                        getMFARequirementsForAuth: async function (input) {
                            if ((await input.requiredSecondaryFactorsForUser).includes(MultiFactorAuth.FactorIds.OTP_EMAIL)) {
                                if ((await input.requiredSecondaryFactorsForTenant).includes(MultiFactorAuth.FactorIds.OTP_EMAIL)) {
                                    return [MultiFactorAuth.FactorIds.OTP_EMAIL]
                                }
                            }
                            // no otp-email required for input.user, with the input.tenant.
                            return []
                        }
                    }
                }
            }
        })
    ]
})

An override for getMFARequirementsForAuth is available, which checks if otp-email is active for the user, and also considers the tenantId to decide if this user should go through the otp-email flow while logging into this tenant. The implementation of shouldRequireOTPEmailForTenant is entirely up to you.

Frontend setup​

The frontend setup is identical to the frontend setup section above.

Protecting frontend and backend routes​

See the section on protecting frontend and backend routes.

Email / SMS sending and design​

By default, the email template used for otp-email login is as shown here, and the default SMS template is as shown here. The method for sending them is via an email and SMS sending service that is available.

If you would like to learn more about this, or change the content of the email, or the method by which they send, checkout the email / SMS delivery section in the recipe docs: