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 additional factors to sign in your users.
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 User pool advanced security features.
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 you set MFA to
required
, you must include the MFA setup in user onboarding so that your user
pool permits them to sign in.
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.
Topics
Considerations for MFA
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 totrue
. -
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.
-
SMS messages require that your users have a phone number attribute. You can set
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 SMS message MFA, you prompt users for their 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 as verified if a user has successfully received a temporary code by SMS 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. 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.
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:
-
You set MFA to optional or required in your user pool.
-
The user has a valid
phone_number
attribute, or has set up an authenticator app for TOTP. -
At least one MFA factor is active.
-
One MFA factor is set as preferred.
Things to know about MFA preference
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 an MFA preference:
-
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
, andSetUserPoolMfaConfig
.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
andUpdateUserPool
. -
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.
-
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 a phone number to sign up in your application. SMS messages become an eligible MFA factor when a user has a
phone_number
attribute. The Schema parameter ofCreateUserPool
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 phone number and the setup of TOTP.
API operations for configuring MFA preferences
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, 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.
You can also set user MFA preferences from the Users tab of the Amazon Cognito console. For more information about the public and confidential authentication models in the Amazon Cognito user pools API, see Using the Amazon Cognito user pools API and user pool endpoints.
Configuring a user pool for multi-factor authentication
You can configure MFA in the Amazon Cognito console.
To configure MFA in the Amazon Cognito console
-
Sign in to the Amazon Cognito console
. -
Choose User Pools.
-
Choose an existing user pool from the list, or create a user pool.
-
Choose the Sign-in experience tab. Locate Multi-factor authentication and choose Edit
-
Choose the MFA enforcement method that you want to use with your user pool.
-
Require MFA. All users in your user pool must sign in with an additional SMS code, or a time-based one-time password (TOTP) factor.
-
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 User pool advanced security features.
-
No MFA. Your users can't register an additional sign-in factor.
-
-
Choose the MFA methods that you support in your app. You can set SMS message or TOTP-generating Authenticator apps as a second factor.
-
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.
-
Choose Save changes.