How do I enable TOTP as a multi-factor authentication for Amazon Cognito user pools?

Last updated: 2020-12-08

I want to enable multi-factor authentication (MFA) for the users of my app. How can I do that with a time-based one-time password (TOTP) token using Amazon Cognito user pools?

Short description

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

Important: Before configuring the TOTP token, keep in mind the following:

  • You must add MFA to your user pool before configuring the TOTP token.
  • TOTP tokens can’t be associated with a user until they attempt to log in to your app, or unless they’re already authenticated.
  • It’s not currently possible to have MFA configured for federated users in a user pool.

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


Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent AWS CLI version.

1.    Run the following AssociateSoftwareToken command from the AWS CLI to start the MFA token generator setup:

aws cognito-idp associate-software-token --access-token eyJraWQiO........ua5Pq3NaA

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

3.    Choose Enter a setup key.

4.    For Account name, enter an account name. For example, BobPhone.

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 you ran in step one.

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

7.    Verify the software token using the time-based password that appears on the screen and the following code:

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

8.    Configure the user's MFA configuration to TOTP MFA using one of the following commands in the AWS CLI:


This command allows users to set their own MFA configuration.

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


This command allows an admin to set a user’s 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 Bob --user-pool-id us-east-1_123456789

9.    Test your setup by authenticating the user in one of these ways:

The Amazon Cognito hosted UI.

The InitiateAuth or AdminInitiateAuth API calls in the AWS CLI.

Note: To authenticate a user with either method, you need the user’s password, username, and software MFA code.

The following examples show how to test user authentication using the AdminInitiateAuth command.

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=Bob,PASSWORD=P@ssw0rd

Important: Make sure to replace the following variables with your own information: user-pool-id, client-id, username, and password. Also, make sure to enable ALLOW_ADMIN_USER_PASSWORD_AUTH flow for the user pool app client by doing the following:

  1. Open the Amazon Cognito console.
  2. Choose Manage User Pools.
  3. Choose your app client and select Show details.
  4. Choose Enable username password auth for admin APIs for authentication (ALLOW_ADMIN_USER_PASSWORD_AUTH).
  5. Choose Save app client changes.

For more information, see Admin authentication flow.

Example output from admin-initiate-auth command

    "ChallengeName": "SOFTWARE_TOKEN_MFA", 
    "ChallengeParameters": {
        "USER_ID_FOR_SRP": "Bob"
    "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=Bob,SOFTWARE_TOKEN_MFA_CODE=123456 --session  Xxz6iadwuWJGN4Z7f4ul5p50IHUqITquoaNxxyDvep.......3A6GokZWKeQ6gkFW4Pgv

Important: Make sure to replace the following variables with your own 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": {}

Did this article help?

Do you need billing or technical support?