Adding MFA to a user pool

A user's preferred MFA method influences the methods they can use to recover their password. Users whose preferred MFA is by email message can't receive a password-reset code by email. Users whose preferred MFA is by SMS message can't receive a password-reset code by SMS.

Your password recovery settings must provide an alternative option when users aren't eligible for your preferred password-reset method. For example, your recovery mechanisms might have email as first priority and email MFA might be an option in your user pool. In this case, add SMS-message account recovery as a second option or use administrative API operations to reset passwords for those users.

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.

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

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.

To change the MFA status of users in response to detected events with advanced security features, activate MFA and set it as optional in the Amazon Cognito user pool console. For more information, see User pool advanced security features.

Email and SMS messages require that your users have email address and phone number attributes respectively. You can set email or phone_number as required attributes in your user pool. In this case, users can't complete sign-up unless they provide a phone number. If you don't set these attributes as required but want to do email or SMS message MFA, you prompt users for their email address or phone number when they sign up. As a best practice, configure your user pool to automatically message users to verify these attributes.

Amazon Cognito counts a phone number or email address as verified if a user has successfully received a temporary code by SMS or email message and returned that code in a VerifyUserAttribute API request. As an alternative, your team can set phone numbers and mark them as verified with an administrative application that performs AdminUpdateUserAttributes API requests.

If you have set MFA to be required and you activated more than one authentication factor, Amazon Cognito prompts new users to select an MFA factor that they want to use. Users must have a phone number to set up SMS message MFA, and an email address to set up email message MFA. If a user doesn't have the attribute defined for any available message-based MFA, Amazon Cognito prompts them to set up TOTP MFA. The prompt to choose an MFA factor (SELECT_MFA_TYPE) and to set up a chosen factor (MFA_SETUP) comes in as a challenge response to InitiateAuth and AdminInitiateAuth API operations.

In the Multi-factor authentication configuration in the Sign-in experience tab of the Amazon Cognito console, you can set MFA to optional or required, or turn it off. The API equivalent of this setting is the MfaConfiguration parameter of CreateUserPool, UpdateUserPool, and SetUserPoolMfaConfig.

Also in the Multi-factor authentication configuration, the MFA methods setting determines the MFA factors that users can set up. The API equivalent of this setting is the SetUserPoolMfaConfig operation.

In the Sign-in experience tab under User account recovery, you can configure the way that your user pool sends messages to users who forget their password. A user’s preferred MFA method can’t have the same delivery method as the highest-priority Recovery message delivery method in your user pool. The API equivalent of this configuration is the AccountRecoverySetting parameter of CreateUserPool and UpdateUserPool.

For example, users can’t set email MFA as preferred when your recovery option is Email only or Email if available, otherwise SMS. Change the delivery method to SMS only or SMS if available, otherwise email.

If you set only one MFA method as available, you don’t need to manage user MFA preferences.

An active SMS configuration automatically makes SMS messages an available MFA method in your user pool.

An active email configuration with your own Amazon SES resources in a user pool, and active advanced security features, automatically makes email messages an available MFA method in your user pool.

When you set MFA to required in a user pool, users can’t enable or disable any MFA methods. You can only set a preferred method.

When you set MFA to optional in a user pool, the hosted UI doesn’t prompt users to set up MFA, but it does prompt users for an MFA code when they have a preferred MFA method.

When you activate advanced security features and configure adaptive-authentication responses in full-function mode, MFA must be optional in your user pool. One of the response options with adaptive authentication is to require MFA for a user whose sign-in attempt is evaluated to contain a level of risk.

The Required attributes setting in the Sign-up experience tab of the console determines whether users must provide an email address or phone number to sign up in your application. Email and SMS messages become eligible MFA factors when a user has the corresponding attribute. The Schema parameter of CreateUserPool sets attributes as required.

When you set MFA to required in a user pool and a user signs in with the hosted UI, Amazon Cognito prompts them to select an MFA method from the available methods for your user pool. The hosted UI handles the collection of an email address or phone number and the setup of TOTP.

In a user self-service model or public application, SetUserMfaPreference, authorized with a signed-in user’s access token, sets MFA configuration.

In an administrator-managed or confidential application, AdminSetUserPreference, authorized with administrative AWS credentials, sets MFA configuration.