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 Asgardeo 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 Asgardeo. 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 Asgardeo 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:

   Classic EditorVisual Editor

   • If you don't have a customized login flow, you can click Add TOTP as a second factor.

     

     This opens the customized login flow with TOTP as a second-factor authenticator:

   • If you have an already customized login flow, you can add a second step and add TOTP as the authenticator.

     

   To add TOTP as a second-factor authenticator using the Visual Editor:

   1. Switch to the Visual Editor tab and go to Predefined Flows > Basic Flows > Add Multi-factor login.

   2. Select Username + Password -> TOTP.

   3. Click Confirm to add TOTP as a second factor to the sign-in flow.

      

   ---

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