Adding MFA to a user pool - Amazon Cognito

Adding MFA to a user pool

Multi-factor authentication (MFA) increases security for your app. It adds a something you have authentication factor to the something you know factor of username and password. You can choose SMS text messages or time-based one-time passwords (TOTP) as second factors to sign in your users.


The first time that a new user signs in to your app, Amazon Cognito issues OAuth 2.0 tokens, even if your user pool requires MFA. The second authentication factor when your user signs in for the first time is their confirmation of the verification message that Amazon Cognito sends to them. If your user pool requires MFA, Amazon Cognito prompts your user to register an additional sign-in factor to use during each sign-in attempt after the first.

With adaptive authentication, you can configure your user pool to require second factor authentication in response to an increased risk level. To add adaptive authentication to your user pool, see Adding advanced security to a user pool.

When you set MFA to required for a user pool, all users must complete MFA to sign in. To sign in, each user must set up at least one MFA factor, such as SMS or TOTP. When you set MFA to required, you must include the MFA setup in user onboarding so that your user pool permits them to sign in.

If you activate SMS as an MFA factor, you can require that users provide phone numbers and have your users verify them during sign-up. If you have set MFA to required and only support SMS as a factor, users must provide phone numbers. Users without phone numbers need your support to add a phone number to their profile before they can sign in. You can use unverified phone numbers for SMS MFA. These numbers will receive verified status after MFA succeeds.

If you have set MFA to be required and you activated SMS and TOTP as supported verification methods, Amazon Cognito prompts new users without phone numbers to set up TOTP MFA. If you have set MFA to be required and the only MFA method you activated is TOTP, Amazon Cognito prompts all new users to set up TOTP MFA the second time they sign in. Amazon Cognito generates a challenge to set up TOTP MFA in response to InitiateAuth and AdminInitiateAuth API operations.

The hosted UI prompts users to set up MFA when you set MFA to be required. When you set MFA to be optional in your user pool, the hosted UI doesn't prompt users. To work with optional MFA, you must build an interface in your app that prompts your users to select that they want to set up MFA, then guides them through the API inputs to verify their additional sign-in factor.

After five unsuccessful attempts to present an MFA code, Amazon Cognito begins the exponential-timeout lockout process described at User pool authentication flow.


Before you set up MFA, consider the following:

  • When you activate MFA in your user pool and choose SMS text message as a second factor, you can send SMS messages to a phone number attribute that you haven't verified in Amazon Cognito. After your user completes SMS MFA, Amazon Cognito sets their phone_number_verified attribute to true.

  • If your account is in the SMS sandbox in the AWS Region that contains the Amazon Simple Notification Service (Amazon SNS) resources for your user pool, you must verify phone numbers in Amazon SNS before you can send an SMS message. For more information, see SMS message settings for Amazon Cognito user pools.

  • Advanced security features require that you activate MFA and set it as optional in the Amazon Cognito user pool console. For more information, see Adding advanced security to a user pool.

Configuring multi-factor authentication

You can configure MFA in the Amazon Cognito console.

To configure MFA in the Amazon Cognito console
  1. Sign in to the Amazon Cognito console.

  2. Choose User Pools.

  3. Choose an existing user pool from the list, or create a user pool.

  4. Choose the Sign-in experience tab. Locate Multi-factor authentication and choose Edit

  5. Choose the MFA enforcement method that you want to use with your user pool.

    Notify users
    1. Require MFA. All users in your user pool must sign in with an additional SMS code or time-based one-time password (TOTP) factor.

    2. Optional MFA - You can give your users the option to register an additional sign-in factor but still permit users who haven't configured MFA to sign in. If you use adaptive authentication, choose this option. For more information about adaptive authentication, see Adding advanced security to a user pool.

    3. No MFA. Your users can't register an additional sign-in factor.

  6. Choose the MFA methods that you support in your app. You can set SMS message or TOTP-generating Authenticator apps as a second factor. We recommend that you implement TOTP-based MFA so that account recovery can use SMS messages.

  7. If you use SMS text messages as a second factor and you haven't configured an IAM role to use with Amazon Simple Notification Service (Amazon SNS) for SMS messages, create one in the console. In the Messaging tab for your user pool, locate SMS and choose Edit. You can also use an existing role that allows Amazon Cognito to send SMS messages to your users for you. For more information, see IAM Roles.

  8. Choose Save changes.