# Adding MFA to a user pool
MFA adds a *something you have* authentication factor to the initial *something you know* factor that is typically a username and password. You can choose SMS text messages, email messages, or time-based one-time passwords (TOTP) as additional factors to sign in your users who have passwords as their primary authentication factor.
Multi-factor authentication (MFA) increases security for the [local users](cognito-terms.md#terms-localuser) in your application. In the case of [federated users](cognito-terms.md#terms-federateduser), Amazon Cognito delegates all authentication processes to the IdP and doesn't offer them additional authentication factors.
**Note**
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 an additional authentication factor in response to an increased risk level. To add adaptive authentication to your user pool, see [Advanced security with threat protection](cognito-user-pool-settings-threat-protection.md).
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. When MFA is required, you must include the MFA setup in user onboarding so that your user pool permits them to sign in.
Managed login prompts users to set up MFA when you set MFA to be required. When you set MFA to be optional in your user pool, managed login 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.
**Topics**
+ [Things to know about user pool MFA](#user-pool-settings-mfa-prerequisites)
+ [User MFA preferences](#user-pool-settings-mfa-preferences)
+ [Details of MFA logic at user runtime](#user-pool-settings-mfa-user-outcomes)
+ [Configure a user pool for multi-factor authentication](#user-pool-configuring-mfa)
+ [SMS and email message MFA](user-pool-settings-mfa-sms-email-message.md)
+ [TOTP software token MFA](user-pool-settings-mfa-totp.md)
## Things to know about user pool MFA
Before you set up MFA, consider the following:
+ Users can either have MFA *or* sign in with passwordless factors, with one exception: passkeys with user verification can satisfy MFA requirements when you set `FactorConfiguration` to `MULTI_FACTOR_WITH_USER_VERIFICATION` in your user pool `WebAuthnConfiguration`.
+ You can't set MFA to required in user pools that support [one-time passwords](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless).
+ You can't add `EMAIL_OTP` or `SMS_OTP` to `AllowedFirstAuthFactors` when MFA is required in your user pool. You can add `WEB_AUTHN` when `FactorConfiguration` is set to `MULTI_FACTOR_WITH_USER_VERIFICATION`.
+ [Choice-based sign-in](authentication-flows-selection-sdk.md#authentication-flows-selection-choice) only offers `PASSWORD` and `PASSWORD_SRP` factors in all app clients when MFA is required in the user pool. For more information about username-password flows, see [Sign-in with persistent passwords](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-password) and [Sign-in with persistent passwords and secure payload](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-srp) in the **Authentication** chapter of this guide.
+ In user pools where MFA is optional, users who have configured an MFA factor can only sign in with username-password authentication flows in choice-based sign-in. These users are eligible for all [client-based sign-in](authentication-flows-selection-sdk.md#authentication-flows-selection-client) flows.
The following table describes the effect of user pool MFA settings and user configuration of MFA factors on users' ability to sign in with passwordless factors.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-mfa.html)
+ 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](managing-users-passwords.md#user-pool-password-reset-and-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.
Amazon Cognito replies to password-reset requests from users who don't have a valid recovery method with an `InvalidParameterException` error response.
The example request body for [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#API_UpdateUserPool_Examples) illustrates an `AccountRecoverySetting` where users can fall back to recovery by SMS message when email-message password reset is unavailable.
+ 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](user-pool-settings-attributes.md). 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](authentication.md#authentication-flow-lockout-behavior).
+ 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](user-pool-sms-settings.md).
+ 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](cognito-user-pool-settings-threat-protection.md).
+ 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](signing-up-users-in-your-app.md).
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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) API request. As an alternative, your team can set phone numbers and mark them as verified with an administrative application that performs [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) and [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API operations.
## User MFA preferences
Users can set up multiple MFA factors. Only one can be active. You can choose the effective MFA preference for your users in user pool settings or from user prompts. A user pools prompts a user for MFA codes when user pool settings and their own user-level settings meet the following conditions:
1. You set MFA to optional or required in your user pool.
1. The user has a valid `email` or `phone_number`attribute, or has set up an authenticator app for TOTP.
1. At least one MFA factor is active.
1. One MFA factor is set as preferred.
### Prevent the use of the same factor for sign-in and MFA
It's possible to configure your user pool in a way that makes one sign-in factor the only available sign-in and MFA option for some or all users. This result can happen when your primary sign-in use case is email-message or SMS-message one-time passwords (OTPs). A user's preferred MFA might be the same type of factor as their sign-in under the following conditions:
+ MFA is required in the user pool.
+ Email and SMS OTP are available sign-in *and* MFA options in the user pool.
+ The user signs in with email or SMS message OTP.
+ They have an email-address attribute but no phone-number attribute, or a phone-number attribute but no email-address attribute.
In this scenario, the user can sign in with an email OTP and complete MFA with an email OTP. This option cancels out the essential function of MFA. Users who sign in with one-time passwords must be able to use different delivery methods for sign-in than for MFA. When users have both SMS and email options, Amazon Cognito automatically assigns a different factor. For example, when a user signs in with email OTP, their preferred MFA is SMS OTP.
Take the following steps to address same-factor authentication when your user pool supports OTP authentication for both sign-in and MFA.
1. Enable both email and SMS OTP as sign-in factors.
1. Enable both email and SMS OTP as MFA factors.
1. Collect
### User pool settings and their effect on MFA options
The configuration of your user pool influences the MFA methods that users can choose. The following are some user pool settings that influence users’ ability to set up MFA.
+ 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserPoolMfaConfig.html) 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-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](user-pool-email.md) 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](cognito-user-pool-settings-threat-protection.md) 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-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.
### Configure MFA preferences for users
You can configure MFA preferences for users in a self-service model with access-token authorization, or in an administrator-managed model with administrative API operations. These operations enable or disable MFA methods and set one of multiple methods as the preferred option. After your user has set an MFA preference, Amazon Cognito prompts them at sign-in to provide a code from their preferred MFA method. Users who have not set a preference receive a prompt to choose a preferred method in a `SELECT_MFA_TYPE` challenge.
+ In a user self-service model or public application, [SetUserMfaPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html), authorized with a signed-in user’s access token, sets MFA configuration.
+ In an administrator-managed or confidential application, [AdminSetUserPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserMFAPreference.html), authorized with administrative AWS credentials, sets MFA configuration.
You can also set user MFA preferences from the **Users** menu of the Amazon Cognito console. For more information about the public and confidential authentication models in the Amazon Cognito user pools API, see [Understanding API, OIDC, and managed login pages authentication](authentication-flows-public-server-side.md#user-pools-API-operations).
## Details of MFA logic at user runtime
To determine the steps to take when users sign in, your user pool evaluates user MFA preferences, [user attributes](user-pool-settings-attributes.md), the [user pool MFA setting](#user-pool-configuring-mfa), [threat protection](cognito-user-pool-settings-adaptive-authentication.md) actions, and [self-service account recovery](managing-users-passwords.md#user-pool-password-reset-and-recovery) settings. It then signs users in, prompts them to choose an MFA method, prompts them to set up an MFA method, or prompts them for MFA. To set up an MFA method, users must provide an [email address or phone number](user-pool-settings-mfa-sms-email-message.md) or [register a TOTP authenticator](user-pool-settings-mfa-totp.md#totp-mfa-set-up-api). They can also set up MFA options and [register a preferred option](#user-pool-settings-mfa-preferences-configure) in advance. The following diagram lists the detailed effects of user pool configuration on sign-in attempts immediately after initial sign-up.
The logic illustrated here applies to SDK-based applications and [managed login](cognito-user-pools-managed-login.md) sign-in, but is less visible in managed login. When you troubleshoot MFA, work backward from your users' outcomes to the user-profile and user-pool configurations that contributed to the decision.
![\[A diagram of the Amazon Cognito user pools decision process for end-user MFA selection.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cup-mfa-decision-tree.png)
The following list corresponds to the numbering in the decision logic diagram and describes each step in detail. A ![\[checkmark\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png) indicates a successful authentication and the conclusion of the flow. A ![\[error\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/error.png) indicates unsuccessful authentication.
1. A user presents their username or username and password at your sign-in screen. If they don't present valid credentials, their sign-in request is denied.
1. If they succeed username-password authentication, determine whether MFA is required, optional, or off. If it is off, the correct username and password results in successful authentication. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If MFA is optional, determine if the user has previously set up a TOTP authenticator. If they have set up TOTP, prompt for TOTP MFA. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. Determine if the adaptive authentication feature of threat protection has required the user to set up MFA. If it hasn't assigned MFA, the user is signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If MFA is required or adaptive authentication has assigned MFA, determine if the user has set an MFA factor as enabled and preferred. If they have, prompt for MFA with that factor. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If the user hasn't set an MFA preference, determine if the user has registered a TOTP authenticator.
1. If the user has registered a TOTP authenticator, determine if TOTP MFA is available in the user pool (TOTP MFA can be disabled after users have previously set up authenticators).
1. Determine whether email-message or SMS-message MFA is also available in the user pool.
1. If neither email nor SMS MFA is available, prompt the user for TOTP MFA. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If email or SMS MFA are available, determine whether the user has the corresponding `email` or `phone_number` attribute. If so, any attribute that isn't the primary method for self-service account recovery and is enabled for MFA is available to them.
1. Prompt the user with a `SELECT_MFA_TYPE` challenge with `MFAS_CAN_SELECT` options that include TOTP and the available SMS or email MFA factors.
1. Prompt the user for the factor that they select in response to the `SELECT_MFA_TYPE` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If the user hasn't registered a TOTP authenticator, or if they have but TOTP MFA is currently disabled, determine whether the user has an `email` or `phone_number` attribute.
1. If the user has only an email address or only a phone number, determine whether that attribute is also the method the user pool implements to send account-recovery messages for password reset. If true, they can't complete sign-in with MFA required and Amazon Cognito returns an error. To activate sign-in for this user, you must add a non-recovery attribute or register a TOTP authenticator for them. ![\[alt text not found\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/error.png)
1. If they have an available non-recovery email address or phone number, determine whether the corresponding email or SMS MFA factor is enabled.
1. If they have a non-recovery email address attribute and email MFA is enabled, prompt them with an `EMAIL_OTP` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If they have a non-recovery phone number attribute and SMS MFA is enabled, prompt them with an `SMS_MFA` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If they don't have an attribute that's eligible for an enabled email or SMS MFA factor, determine whether TOTP MFA is enabled. If TOTP MFA is disabled, they can't complete sign-in with MFA required and Amazon Cognito returns an error. To activate sign-in for this user, you must add a non-recovery attribute or register a TOTP authenticator for them. ![\[alt text not found\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/error.png)
**Note**
This step has already been evaluated as **No** if the user has a TOTP authenticator but TOTP MFA is disabled.
1. If TOTP MFA is enabled, present the user with a `MFA_SETUP` challenge with `SOFTWARE_TOKEN_MFA` in the `MFAS_CAN_SETUP` options. To complete this challenge, you must separately register a TOTP authenticator for the user and respond with `"ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "SESSION": "[Session ID from VerifySoftwareToken]}"`.
1. After the user responds to the `MFA_SETUP` challenge with the session token from a [VerifySoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html) request, prompt them with an `SOFTWARE_TOKEN_MFA` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If the user has both an email address and phone number, determine which attribute, if any, is the primary method for account-recovery messages for password reset.
1. If self-service account recovery is disabled, either attribute can be used for MFA. Determine whether one or both of the email and SMS MFA factors are enabled.
1. If both attributes are enabled as an MFA factor, prompt the user with a `SELECT_MFA_TYPE` challenge with `MFAS_CAN_SELECT` options `SMS_MFA` and `EMAIL_OTP`.
1. Prompt them for the factor that they select in response to the `SELECT_MFA_TYPE` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
1. If only one attribute is an eligible MFA factor, prompt them with a challenge for the remaining factor. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
This outcome happens in the following scenarios.
1. When they have `email` and `phone_number` attributes, SMS and email MFA are enabled, and the primary account-recovery method is by email or SMS message.
1. When they have `email` and `phone_number` attributes, only SMS MFA or email MFA is enabled, and self-service account recovery is disabled.
1. If the user hasn't registered a TOTP authenticator and has neither an `email` nor `phone_number` attribute, prompt them with an `MFA_SETUP` challenge. The list in `MFAS_CAN_SETUP` includes all enabled MFA factors in the user pool that aren't the primary account-recovery option. They can respond to this challenge with `ChallengeResponses` for email or TOTP MFA. To set up SMS MFA, add a phone number attribute separately and restart authentication.
For TOTP MFA, respond with `"ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "SESSION": "[Session ID from VerifySoftwareToken]"}`.
For email MFA, respond with `"ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "email": "[user's email address]"}`.
1. Prompt them for the factor that they select in response to the `SELECT_MFA_TYPE` challenge. If they successfully respond to the MFA challenge, they're signed in. ![\[Green circular icon with a checkmark symbol inside.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/checkmark.png)
## Configure a user pool for multi-factor authentication
You can configure MFA in the Amazon Cognito console or with the [SetUserPoolMfaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserPoolMfaConfig.html) API operation and SDK methods.
**To configure MFA in the Amazon Cognito console**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).
1. Choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Sign-in** menu. Locate **Multi-factor authentication** and choose **Edit**.
1. Choose the **MFA enforcement** method that you want to use with your user pool.
![\[A screenshot from the Amazon Cognito console with MFA options.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cup-mfa.png)
1. **Require MFA**. All users in your user pool must sign in with an additional SMS, email, or time-based one-time password (TOTP) code as an additional authentication factor.
1. **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 [Advanced security with threat protection](cognito-user-pool-settings-threat-protection.md).
1. **No MFA**. Your users can't register an additional sign-in factor.
1. Choose the **MFA methods** that you support in your app. You can set **Email message**, **SMS message** or TOTP-generating **Authenticator apps** as a second factor.
1. 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 **Authentication methods** menu 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).
If you use email messages as a second factor and you haven't configured an originating identity to use with Amazon Simple Email Service (Amazon SES) for email messages, create one in the console. You must choose the **Send email with SES** option. In the **Authentication methods** menu for your user pool, locate **Email** and choose **Edit**. Select a **FROM email address** from the available verified identities in the list. If you choose a verified domain, for example `example.com`, you must also configure a **FROM sender name** in the verified domain, for example `admin-noreply@example.com`.
1. Choose **Save changes**.
# SMS and email message MFA
SMS and email MFA messages confirm that users have access to a message destination before they can sign in. They confirm that they not only have access to a password, but to the SMS messages or the email inbox of the original user. Amazon Cognito requests that users provide a short code that your user pool sent after they successfully provide a username and password.
SMS and email message MFA require no additional configuration after your user adds an email address or phone number to their profile. Amazon Cognito can send messages to unverified email addresses and phone numbers. When a user completes their first MFA, Amazon Cognito marks their email address or phone number as verified.
MFA authentication begins when a user with MFA enters their username and password in your application. Your application submits these initial parameters in an SDK method that invokes an [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) or [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API request. The `ChallengeParameters` in the API response includes a `CODE_DELIVERY_DESTINATION` value that indicates where the authorization code was sent. In your application, display a form that prompts the user to check their phone and includes an input element for the code. When they enter their code, submit it in a challenge-response API request to complete the sign-in process.
After a user with MFA signs in with username and password in the [managed login](cognito-user-pools-managed-login.md) pages, they're automatically prompted for the MFA code.
User pools send SMS messages for MFA and other Amazon Cognito notifications with Amazon Simple Notification Service (Amazon SNS) resources in your AWS account. Similarly, users pools send email messages with Amazon Simple Email Service (Amazon SES) resources in your account. These linked services incur their own costs on your AWS bill for message delivery. They also have additional requirements for sending messages at production volumes. See the following links for more information:
+ [SMS message settings for Amazon Cognito user pools](user-pool-sms-settings.md)
+ [Worldwide SMS Pricing](https://aws.amazon.com/sns/sms-pricing/)
+ [Email settings for Amazon Cognito user pools](user-pool-email.md)
+ [Amazon SES pricing](https://aws.amazon.com/ses/pricing)
## Considerations for SMS and email message MFA
+ To permit users to sign in with email MFA, your user pool must have the following configuration options:
1. You have the Plus or Essentials feature plan in your user pool. For more information, see [User pool feature plans](cognito-sign-in-feature-plans.md).
1. Your user pool sends email messages with your own Amazon SES resources. For more information, see [Amazon SES email configuration](user-pool-email.md#user-pool-email-developer).
+ The MFA code is valid for the **Authentication flow session duration** that you set for your app client.
Set the duration of an authentication flow session in the Amazon Cognito console in the **App clients** menu when you **Edit** your app client. You can also set the authentication flow session duration in a `CreateUserPoolClient` or `UpdateUserPoolClient` API request. For more information, see [An example authentication session](authentication.md#amazon-cognito-user-pools-authentication-flow).
+ When a user successfully provides a code from an SMS or email message that Amazon Cognito sent to an unverified phone number or email address, Amazon Cognito marks the corresponding attribute as verified.
+ For a user to make a self-service change to the value of a phone number or email address that's associated with MFA, they must sign in and authorize the request with an access token. If they can't access their current phone number or email address, they can't sign in. Your team must change these values with administrator AWS credentials in [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API requests.
+ After you [configure SMS](user-pool-sms-settings.md) in your user pool, you can't disable SMS messages as an available MFA factor.
# TOTP software token MFA
When you set up TOTP software token MFA in your user pool, your user signs in with a username and password, then uses a TOTP to complete authentication. After your user sets and verifies a username and password, they can activate a TOTP software token for MFA. If your app uses the Amazon Cognito managed login to sign in users, your user submits their username and password, and then submits the TOTP password on an additional sign-in page.
You can activate TOTP MFA for your user pool in the Amazon Cognito console, or you can use Amazon Cognito API operations. At the user pool level, you can call [SetUserPoolMfaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserPoolMfaConfig.html) to configure MFA and enable TOTP MFA.
**Note**
If you haven't activated TOTP software token MFA for the user pool, Amazon Cognito can't use the token to associate or verify users. In this case, users receive a `SoftwareTokenMFANotFoundException` exception with the description `Software Token MFA has not been enabled by the userPool`. If you deactivate software token MFA for the user pool later, users who previously associated and verified a TOTP token can continue to use it for MFA.
Configuring TOTP for your user is a multi-step process where your user receives a secret code that they validate by entering a one-time password. Next, you can enable TOTP MFA for your user or set TOTP as the preferred MFA method for your user.
When you configure your user pool to require TOTP MFA and your users sign up for your app in managed login, Amazon Cognito automates the user process. Amazon Cognito prompts your user to choose an MFA method, displays a QR code to set up their authenticator app, and verifies their MFA registration. In user pools where you have allowed users to choose between SMS and TOTP MFA, Amazon Cognito also presents your user with a choice of method.
**Important**
When you have an AWS WAF web ACL associated with a user pool, and a rule in your web ACL presents a CAPTCHA, this can cause an unrecoverable error in managed login TOTP registration. To create a rule that has a CAPTCHA action and doesn't affect managed login TOTP, see [Configuring your AWS WAF web ACL for managed login TOTP MFA](#totp-waf). For more information about AWS WAF web ACLs and Amazon Cognito, see [Associate an AWS WAF web ACL with a user pool](user-pool-waf.md).
To implement TOTP MFA in a custom-built UI with an AWS SDK and the [Amazon Cognito user pools API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html), see [Configuring TOTP MFA for a user](#totp-mfa-set-up-api).
To add MFA to your user pool, see [Adding MFA to a user pool](user-pool-settings-mfa.md).
**TOTP MFA considerations and limitations**
1. Amazon Cognito supports software token MFA through an authenticator app that generates TOTP codes. Amazon Cognito doesn't support hardware-based MFA.
1. When your user pool requires TOTP for a user who has not configured it, your user receives a one-time access token that your app can use to activate TOTP MFA for the user. Subsequent sign-in attempts fail until your user has registered an additional TOTP sign-in factor.
+ A user who signs up in your user pool with the `SignUp` API operation or through managed login receives one-time tokens when the user completes sign-up.
+ After you create a user, and the user sets their initial password, Amazon Cognito issues one-time tokens from managed login to the user. If you set a permanent password for the user, Amazon Cognito issues one-time tokens when the user first signs in.
+ Amazon Cognito doesn't issue one-time tokens to an administrator-created user who signs in with the [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) or [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API operations. After your user succeeds in the challenge to set their initial password, or if you set a permanent password for the user, Amazon Cognito immediately challenges the user to set up MFA.
1. If a user in a user pool that requires MFA has already received a one-time access token but hasn't set up TOTP MFA, the user can't sign in with managed login until they have set up MFA. Instead of the access token, you can use the `session` response value from an `MFA_SETUP` challenge to [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) or [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) in an [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html) request.
1. If your users have set up TOTP, they can use it for MFA, even if you deactivate TOTP for the user pool later.
1. Amazon Cognito only accepts TOTPs from authenticator apps that generate codes with the HMAC-SHA1 hash function. Codes generated with SHA-256 hashing return a `Code mismatch` error.
## Configuring TOTP MFA for a user
When a user first signs in, your app uses their one-time access token to generate the TOTP private key and present it to your user in text or QR code format. Your user configures their authenticator app and provides a TOTP for subsequent sign-in attempts. Your app or managed login presents the TOTP to Amazon Cognito in MFA challenge responses.
Under some circumstances, managed login prompts new users to set up a TOTP authenticator. for more information, see [Details of MFA logic at user runtime](user-pool-settings-mfa.md#user-pool-settings-mfa-user-outcomes).
**Topics**
+ [Associate the TOTP software token](#user-pool-settings-mfa-totp-associate-token)
+ [Verify the TOTP token](#user-pool-settings-mfa-totp-verification)
+ [Sign in with TOTP MFA](#user-pool-settings-mfa-totp-sign-in)
+ [Remove the TOTP token](#user-pool-settings-mfa-totp-remove)
### Associate the TOTP software token
To associate the TOTP token, send your user a secret code that they must validate with a one-time password. Associating the token requires three steps.
1. When your user chooses TOTP software token MFA, call [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html) to return a unique generated shared secret key code for the user account. You can authorize AssociateSoftwareToken with either an access token or a session string.
1. Your app presents the user with the private key, or a QR code that you generate from the private key. Your user must enter the key into a TOTP-generating app like Google Authenticator, either by scanning the QR code that your application generates from the private key or by manually entering the key.
1. Your user enters the key, or scans the QR code into a authenticator app such as Google Authenticator, and the app begins generating codes.
### Verify the TOTP token
Next, verify the TOTP token. Request sample codes from your user and provide them to the Amazon Cognito service to confirm that the user is successfully generating TOTP codes, as follows.
1. Your app prompts your user for a code to demonstrate that they have set up their authenticator app properly.
1. The user's authenticator app displays a temporary password. The authenticator app bases the password on the secret key you gave to the user.
1. Your user enters their temporary password. Your app passes the temporary password to Amazon Cognito in a `[VerifySoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html)` API request.
1. Amazon Cognito has retained the secret key associated with the user, and generates a TOTP and compares it with the one that your user provided. If they match, `VerifySoftwareToken` returns a `SUCCESS` response.
1. Amazon Cognito associates the TOTP factor with the user.
1. If the `VerifySoftwareToken` operation returns an `ERROR` response, make sure that the user's clock is correct and that they have not exceeded the maximum number of retries. Amazon Cognito accepts TOTP tokens that are within 30 seconds before or after the attempt, to account for minor clock skew. When you have resolved the issue, try the VerifySoftwareToken operation again.
### Sign in with TOTP MFA
At this point, your user signs in with the time-based one-time password. The process is as follows.
1. Your user enters their username and password to sign in to your client app.
1. The TOTP MFA challenge is invoked, and your user is prompted by your app to enter a temporary password.
1. Your user gets the temporary password from an associated TOTP-generating app.
1. Your user enters the TOTP code into your client app. Your app notifies the Amazon Cognito service to verify it. For each sign-in, [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) should be called to get a response to the new TOTP authentication challenge.
1. If the token is verified by Amazon Cognito, the sign-in is successful and your user continues with the authentication flow.
### Remove the TOTP token
Finally, your app should allow your user to deactivate their TOTP configuration. Currently, you can't delete a user's TOTP software token. To replace your user's software token, associate and verify a new software token. To deactivate TOTP MFA for a user, call [SetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html) to modify your user to use no MFA, or only SMS MFA.
1. Create an interface in your app for users who want to reset MFA. Prompt a user in this interface to enter their password.
1. If Amazon Cognito returns a TOTP MFA challenge, update your user's MFA preference with [SetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html).
1. In your app, communicate to your user that they have deactivated MFA and prompt them to sign in again.
## Configuring your AWS WAF web ACL for managed login TOTP MFA
When you have an AWS WAF web ACL associated with a user pool, and a rule in your web ACL presents a CAPTCHA, this can cause an unrecoverable error in managed login TOTP registration. AWS WAF CAPTCHA rules *only* have this effect on TOTP MFA in managed login and the classic hosted UI. SMS MFA is unaffected.
Amazon Cognito displays the following error when your CAPTCHA rule doesn't let a user complete TOTP MFA setup.
Request not allowed due to WAF captcha.
This error results when AWS WAF prompts for a CAPTCHA in response to [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html) and [VerifySoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html) API requests that your user pool makes in the background. To create a rule that has a CAPTCHA action and doesn't affect TOTP in managed login pages, exclude the `x-amzn-cognito-operation-name` header values of `AssociateSoftwareToken` and `VerifySoftwareToken` from the CAPTCHA action in your rule.
The following screenshot shows an example AWS WAF rule that applies a CAPTCHA action to all requests that don't have a `x-amzn-cognito-operation-name` header value of `AssociateSoftwareToken` or `VerifySoftwareToken`.
![\[A screenshot of a AWS WAF rule that applies a CAPTCHA action to all requests that don't have a x-amzn-cognito-operation-name header value of AssociateSoftwareToken or VerifySoftwareToken.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/cup-WAF-rule-TOTP.png)
For more information about AWS WAF web ACLs and Amazon Cognito, see [Associate an AWS WAF web ACL with a user pool](user-pool-waf.md).