Adding MFA to a user pool

You can have either required MFA or passwordless sign-in factors in your user pool. You can't set MFA to required in user pools that support one-time passwords or passkeys. You can't activate choice-based sign-in with the USER_AUTH flow in user pools that require MFA.

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.

Users can't receive MFA and password reset codes at the same email address or phone number. If they use one-time passwords (OTPs) from email messages for MFA, they must use SMS messages for account recovery. If they use OTPs from SMS messages for MFA, they must use email messages for account recovery. In user pools with MFA, users might be unable to complete self-service password recovery if they have attributes for their email address but no phone number, or their phone number but no email address.

To prevent the state where users can't reset their passwords in user pools with this configuration, set the email and phone_number attributes as required. As an alternative, you can set up processes that always collect and set those attributes when users sign up or when your administrators create user profiles. When users have both attributes, Amazon Cognito automatically sends password-reset codes to the destination that is not the user's MFA factor.

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

After five unsuccessful attempts to present an MFA code, Amazon Cognito begins the exponential-timeout lockout process described at Lockout behavior for failed sign-in attempts.

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 threat protection, activate MFA and set it as optional in the Amazon Cognito user pool console. For more information, see Advanced security with threat protection.

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 menu 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 menu, under User account recovery, you can configure the way that your user pool sends messages to users who forget their password. A user's MFA method can’t have the same MFA delivery method as the user pool delivery method for forgot-password codes. The API parameter for the forgot-password delivery method is the AccountRecoverySetting parameter of CreateUserPool and UpdateUserPool.

For example, users can’t set up email MFA when your recovery option is Email only. This is because you can't enable email MFA and set the recovery option to Email only in the same user pool. When you set this option to Email if available, otherwise SMS, email is the priority recovery option but your user pool can fall back to SMS message when a user isn't eligible for email-message recovery. In this scenario, users can set email MFA as preferred and can only receive an SMS message when they attempt to reset their password.

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 the Essentials or Plus feature plan, 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, managed login 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 threat protection 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 menu 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 managed login, Amazon Cognito prompts them to select an MFA method from the available methods for your user pool. Managed login handles the collection of an email address or phone number and the setup of TOTP. The diagram that follows demonstrates the logic behind the options that Amazon Cognito presents to users.

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.