AWS cognito documentation change
Summary
Updated MFA documentation with detailed decision logic flow, including diagrams and step-by-step explanations of MFA selection process. Added information about MFA setup challenges and API operations.
Security assessment
The changes provide more detailed documentation about MFA implementation and decision logic, which is a security feature. However, there is no evidence this change addresses a specific security vulnerability or incident.
Diff
diff --git a/cognito/latest/developerguide/user-pool-settings-mfa.md index 3a84be210..f48733f35 100644 --- a/cognito/latest/developerguide/user-pool-settings-mfa.md +++ b/cognito/latest/developerguide/user-pool-settings-mfa.md @@ -5 +5 @@ -Things to knowUser MFA preferencesConfiguring multi-factor authentication +Things to knowUser MFA preferencesMFA logicConfigure MFA @@ -27 +27,2 @@ Managed login prompts users to set up MFA when you set MFA to be required. When - * Configuring a user pool for multi-factor authentication + * Details of MFA logic at user runtime + * Configure a user pool for multi-factor authentication @@ -105 +106 @@ The **Required attributes** setting in the **Sign-up** menu of the console deter - * 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. + * 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. @@ -110 +111 @@ The **Required attributes** setting in the **Sign-up** menu of the console deter -### API operations for configuring MFA preferences +### Configure MFA preferences for users @@ -123 +124 @@ You can also set user MFA preferences from the **Users** menu of the Amazon Cogn -## Configuring a user pool for multi-factor authentication +## Details of MFA logic at user runtime @@ -125 +126,82 @@ You can also set user MFA preferences from the **Users** menu of the Amazon Cogn -You can configure MFA in the Amazon Cognito console. +To determine the steps to take when users sign in, your user pool evaluates user MFA preferences, [user attributes](./user-pool-settings-attributes.html), the user pool MFA setting, [threat protection](./cognito-user-pool-settings-adaptive-authentication.html) actions, and [self-service account recovery](./managing-users-passwords.html#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.html) or [register a TOTP authenticator](./user-pool-settings-mfa-totp.html#totp-mfa-set-up-api). They can also set up MFA options and register a preferred option 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.html) 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. + + + +The following list corresponds to the numbering in the decision logic diagram and describes each step in detail. A  indicates a successful authentication and the conclusion of the flow. A  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. + + 2. 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.  + + 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.  + + 2. 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.  + + 3. 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.  + + 4. 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). + + 2. Determine whether email-message or SMS-message MFA is also available in the user pool. + + 3. 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.  + + 4. 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. + + 5. 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. + + 6. 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.  + + 5. 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. + + 6. 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.  + + 1. If they have an available non-recovery email address or phone number, determine whether the corresponding email or SMS MFA factor is enabled. + + 2. 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.  + + 3. 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.  + + 4. 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.  + +###### Note + +This step has already been evaluated as **No** if the user has a TOTP authenticator but TOTP MFA is disabled. + + 5. 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]}"`. + + 6. 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.  + + 7. 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. + + 2. 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`. + + 3. 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.  + + 4. 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.  + +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. + + 2. When they have `email` and `phone_number` attributes, only SMS MFA or email MFA is enabled, and self-service account recovery is disabled. + + 8. 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.  + + + + +## 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.