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:

• Google Authenticator
• Authy

Note

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.

Prerequisites

• To get started, you need to register an application with WSO2 Identity Server. You can register your own application or use one of the sample applications provided.

• Download and install one of the authenticator apps mentioned above.

Note

• 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.

      

   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.

   Note

   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(1);
     executeStep(2, {
         authenticatorParams: {
           common: {
               'enrolUserInAuthenticationFlow': enrolUserInAuthenticationFlow
           }
         }
     }, {
         onSuccess: function (context) {
           Log.info("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.

   Note

   • This step is prompted only when the user attempts to log in for the first time.
   • This step will not be prompted if you have disabled enrolling in TOTP during first login.

   

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

5. Enter the TOTP:

   

6. Click Continue to continue login.

Note

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.