Menu
Amazon Cognito
Developer Guide

TOTP Software Token MFA

Your user is challenged to complete authentication using a time-based one-time (TOTP) password after their user name and password have been verified when TOTP software token MFA is enabled. If your app is using the Amazon Cognito hosted UI to sign in users, the UI shows a second page for your user to enter the TOTP password after they submit their user name and password.

You can enable TOTP MFA for your user pool in the Amazon Cognito console, through the Amazon Cognito hosted UI, or using Amazon Cognito APIs. At the user pool level, you can configure MFA and enable TOTP MFA by calling SetUserPoolMfaConfig.

Note

If TOTP software token MFA isn't enabled for the user pool, users can't associate or verify with the token. They receive a SoftwareTokenMFANotFoundException exception, as follows: "Software Token MFA has not been enabled by the userPool."

Configuring TOTP for your user is a multi-step process where your user receives a secret code that they validate by entering a one-time password. Next, you can enable TOTP MFA for your user or set TOTP as the preferred MFA method for your user.

To add MFA to your user pool, see Adding Multi-Factor Authentication (MFA) to a User Pool.

Associate the TOTP Token

  1. When your user chooses TOTP software token MFA, call AssociateSoftwareToken to return a unique generated shared secret key code for the user account. The request for this API method takes an access token or a session string, but not both. As a convenience, you can distribute the secret key as a quick response (QR) code.

  2. The key code or QR code appears on your app and your user needs to enter it into a TOTP-generating app such as Google Authenticator.

  3. Your user enters the key code into the TOTP-generating app to associate a new account with your client app.

Verify the TOTP Token

  1. After a new TOTP account is associated with your app, it generates a temporary password.

  2. Your user enters the temporary password into your app, which responds with a call to VerifySoftwareToken. On the Amazon Cognito service server, a TOTP code is generated and compared with your user's temporary password. If they match, then the service marks it as verified.

  3. If the code is correct, check that the time used is in the range and within the maximum number of retries. If your user passes all of the steps, the verification is complete.

    Or, if the code is wrong, the verification cannot be finished and your user can either try again or cancel. We recommend that your user sync the time of their TOTP-generating app.

Sign in with TOTP MFA

  1. Your user enters their user name and password to sign in to your client app.

  2. The TOTP MFA challenge is invoked and your user is prompted by your app to enter a temporary password.

  3. Your user gets the temporary password from an associated TOTP-generating app.

  4. Your user enters the TOTP code into your client app. Your app notifies the Amazon Cognito service to verify it. For each sign-in, RespondToAuthChallenge should be called to get a response to the new TOTP authentication challenge.

  5. If the token is verified by Amazon Cognito, the sign-in is successful and your user continues with the authentication flow.

Remove the TOTP Token

  1. Your app should allow your user to remove the TOTP token.

  2. Your client app should ask your user to enter their password.

  3. If the password is correct, remove the TOTP token.

    Note

    A delete TOTP software token operation is not currently available in the API. This functionality is planned for a future release. Use SetUserMFAPreference to disable TOTP MFA for an individual user.