Skip to content

Add MFA with TOTP

The Time-based One-Time Password (TOTP) is a temporary passcode, generated by an algorithm that can be used only once. The algorithm that generates each password uses the current time of the day, which ensures that each password is unique. TOTP is considered more secure because the passcode is valid only for a short window of time. The TOTP generated by WSO2 Identity Server is valid for 30 seconds.

To use TOTP as a multi-factor authentication(MFA) option, application users need to have an authenticator app that can scan the QR code and generate a one-time password. Some authenticator apps are:


TOTP authenticators use the TOTP specification to calculate access tokens based on the current time and the secret key shared between the user and the identity provider.



  • You can use TOTP for multi-factor authentication only if a previous authentication step is configured with username and password or another factor that can validate user credentials.
  • TOTP cannot be used as the first step of your login flow.
  • Federated users (users who are authenticated using external IdPs) can log in with TOTP MFA option.

Enable TOTP for an app

Follow the steps given below to enable TOTP as the second factor in the login flow of your application.

  1. On the WSO2 Identity Server Console, go to Applications.

  2. Select the application for which TOTP needs to be added.

  3. Go to the Login Flow tab of the application and add the TOTP authenticator as follows:

    1. Go to Predefined Flows > Add Multi-factor Login.

    2. Select Username + Password -> TOTP.

    3. Click Confirm to add passwordless login with email OTP to the sign-in flow.

      Configuring TOTP authenticator in Asgardeo using the visual editor

    4. Select Enable backup codes if you wish to allow users to use backup codes to log in to the application. Learn more about configuring backup codes for users.

  4. Click Update to save your changes.

Disable enrolling in TOTP during first login

TOTP enrollment during the first login is enabled by default for all applications.

Administrators of an organization can configure their business applications to disable TOTP enrollment during the login flow of the users.

To disable TOTP enrollment during login:

  1. On the WSO2 Identity Server Console, enable TOTP for a selected application.
  2. Turn on Conditional Authentication by switching the toggle.
  3. Add the following authentication script.


    The authenticatorParams method has been added to executestep(2), assuming that TOTP is configured in step 2 of the authentication process. If you have configured TOTP in a different step, add the authenticatorParams method to the relevant step.

    var enrolUserInAuthenticationFlow = "false";
    var onLoginRequest = function (context) {
      executeStep(2, {
          authenticatorParams: {
            common: {
                'enrolUserInAuthenticationFlow': enrolUserInAuthenticationFlow
      }, {
          onSuccess: function (context) {
  "Successfully managed login flow");

    Enable enrolling in TOTP at first login

    To enable enrolling in TOTP the first time a user logs in, use any of the following approaches:

    • Update the value of enrolUserInAuthenticationFlow parameter to true.
      var enrolUserInAuthenticationFlow = "true";
    • Turn off Conditional Authentication by switching the toggle.
  4. Click Update to save your changes.

Try it out

Application users can enroll for TOTP authentication when they login to the business application for the first time. Given below are the steps that a user will follow:

  1. Download an authenticator app to a mobile device.
  2. Try to log in to the application by providing credentials. The user is prompted with a QR code.
  3. Scan the QR code using the authenticator app, select the checkbox, and click Continue.


    QR code for TOTP authenticator in WSO2 Identity Server

  4. Check the authenticator app and see that the TOTP is generated.

  5. Enter the TOTP:

    User enters OTP token in WSO2 Identity Server

  6. Click Continue to continue login.


If the QR code is deleted from the authenticator app, there is no way to recover it from the application. In such a scenario, the user should re-enroll for TOTP through the Multi Factor Authentication option in the My Account portal.

Learn more about enrolling TOTP from My Account.