How do I activate TOTP multi-factor authentication for Amazon Cognito user pools?

Short description

To activate TOTP MFA for your app users, set up TOTP software token MFA for your user pool.

Important: Before you configure the TOTP token, review the following requirements:

• You must add MFA to your user pool.
• TOTP tokens can't be associated with a user until the user tries to log in to your app, or unless they're already authenticated.
• MFA doesn't support federated users in a user pool.

The following is an example of how to use the AWS Command Line Interface (AWS CLI) and Google Authenticator to set up TOTP MFA.

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

1. To start the MFA token generator setup, run the following associate-software-token AWS CLI command:

   aws cognito-idp associate-software-token --access-token eyJraWQiO........ua5Pq3NaA
   {
       "SecretCode":
       "AETQ6XXMDFYMEPFQQ7FD4HKXXXXAOY3MBXIVRBLRXX3SXLSHHWOA"
   }

2. Open the Google Authenticator homepage, and then choose Get started.

3. Choose Enter a setup key.

4. For Account name, enter an account name.
   Note: The account name can be any string identifier.

5. For the Your key text input, copy and paste the secret code that was generated from the AssociateSoftwareToken command that you ran in step 1.

6. Choose Type of key, and then select Time based.

7. Confirm the software token that uses the time-based password that appears on the screen and in the following code:

   aws cognito-idp verify-software-token --access-token eyJraWQiO........ua5Pq3NaA --user-code 269194 --friendly-device-name ExampleName
   {
       "Status": "SUCCESS"
   }

8. To configure the user's MFA configuration to TOTP MFA, run either the set-user-mfa-preference or admin-set-user-mfa-preference AWS CLI command:
   Example set-user-mfa-preference command

   aws cognito-idp set-user-mfa-preference --software-token-mfa-settings Enabled=true,PreferredMfa=true --access-token eyJraWQiO........ua5Pq3NaA

   Note: This command allows users to set their own MFA configuration.
   Example admin-set-user-mfa-preference command

   aws cognito-idp admin-set-user-mfa-preference --software-token-mfa-settings Enabled=true,PreferredMfa=true --username ExampleName --user-pool-id us-east-1_123456789

   Note: This command allows an admin to set a user's MFA configuration.

9. To activate ALLOW_ADMIN_USER_PASSWORD_AUTH flow for the user pool app client, open the Amazon Cognito console.

10. Choose Manage User Pools.

11. Choose your app client and select Show details.

12. Choose Enable username password auth for admin APIs for authentication (ALLOW_ADMIN_USER_PASSWORD_AUTH).

13. Choose Save app client changes.

14. To test your setup, authenticate the user with one of the following methods:
    The Amazon Cognito hosted UI.
    The InitiateAuth, AdminInitiateAuth, or RespondToAuthChallenge API calls in the AWS CLI.
    Note: To authenticate a user with either method, you must have the user's password, username, and software MFA code.
    Example admin-initiate-auth command

    aws cognito-idp admin-initiate-auth --user-pool-id us-east-1_123456789 --client-id 3n4b5urk1ft4fl3mg5e62d9ado --auth-flow ADMIN_USER_PASSWORD_AUTH --auth-parameters USERNAME=ExampleName,PASSWORD=P@ssw0rd

    Note: Replace the following variables with your information: user-pool-id, client-id, username, and password.

    Example output from admin-initiate-auth command

    {    
        "ChallengeName": "SOFTWARE_TOKEN_MFA", 
        "ChallengeParameters": {
            "FRIENDLY_DEVICE_NAME": "ExampleDevice", 
            "USER_ID_FOR_SRP": "ExampleName"
        }, 
        "Session": "Xxz6iadwuWJGN4Z7f4ul5p50IHUqITquoaNxxyDvep.......3A6GokZWKeQ6gkFW4Pgv"
    }

    Example admin-respond-to-auth-challenge command

    aws cognito-idp admin-respond-to-auth-challenge --user-pool-id us-east-1_123456789 --client-id 3n4b5urk1ft4fl3mg5e62d9ado --challenge-name SOFTWARE_TOKEN_MFA --challenge-responses USERNAME=ExampleName,SOFTWARE_TOKEN_MFA_CODE=123456 --session  Xxz6iadwuWJGN4Z7f4ul5p50IHUqITquoaNxxyDvep.......3A6GokZWKeQ6gkFW4Pgv

    Note: Replace the following variables with your information: client-id, username, and software_token_MFA_Code.

    Example output from admin-respond-to-auth-challenge command

    {    
        "AuthenticationResult": {
            "ExpiresIn": 3600, 
            "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMi.......dlbjrtyizlLzZZ5fjjCgL__AVHEzYycjJs_h3i-ly_KixDNtz9VEC",
        
            "TokenType": "Bearer", 
            "NewDeviceMetadata": {
        
                "DeviceKey": "us-east-1_28abrd7-10f7-9fc6-a931-3ede1c8ckd75", 
                "DeviceGroupKey": "-Gqkj3brS"
           
            }, 
            "IdToken": "eyJraWQiOiIzcFFSV29Pb........mNMbE_vvPkQYBuA9ackoER1aSABFGaKK4BpgPjMn7la_A", 
            "AccessToken": "eyJraWQiOi...........qwvQq4awt63TyWw"
       
        }, 
        "ChallengeParameters": {}
    }

Related information

Authentication with Amazon Cognito user pools