AWS cognito medium security documentation change
Summary
Updated documentation about email/phone verification workflows, added details about AttributesRequireVerificationBeforeUpdate configuration, username configuration impacts, and behavioral examples
Security assessment
The changes clarify security-critical behavior around attribute verification during updates, specifically explaining how unverified attributes affect sign-in capabilities. The addition of the AttributesRequireVerificationBeforeUpdate property documentation and scenarios where users might lose sign-in access without verification demonstrates concrete security controls to prevent account takeover via unverified attribute changes.
Diff
diff --git a/cognito/latest/developerguide/signing-up-users-in-your-app.md b/cognito/latest/developerguide/signing-up-users-in-your-app.md index 9c5e241e9..42034e9bc 100644 --- a/cognito/latest/developerguide/signing-up-users-in-your-app.md +++ b/cognito/latest/developerguide/signing-up-users-in-your-app.md @@ -380 +380 @@ If you don't require the user to receive and enter a confirmation code at sign-u -When a user updates their email address or phone number in your app, Amazon Cognito immediately sends a message with a verification code to a user if you configured your user pool to automatically verify that attribute. The user must then provide the code from the verification message to your app. Your app then submits the code in a [VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) API request to complete verification of the new attribute value. +In user pools that you configure with multiple sign-in names, users can enter a phone number or an email address as their username at sign-in. When they update their email address or phone number in your app, Amazon Cognito can immediately send them a message with a code that verifies their ownership of the new attribute value. To enable automatic sending of these verification codes, see [Configuring email or phone verification](./user-pool-settings-email-phone-verification.html). @@ -382 +382 @@ When a user updates their email address or phone number in your app, Amazon Cogn -If your user pool doesn’t require that users verify an updated email address or phone number, Amazon Cognito immediately changes the value of an updated `email ` or `phone_number` attribute and marks the attribute as unverified. Your user can’t sign in with an unverified email or phone number. They must complete verification of the updated value before they can use that attribute as a sign-in alias. +Users who receive a verification code must provide that code back to Amazon Cognito in a [VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) request. After they provide the code, their attribute is marked as verified. Typically, when users update their email address or phone number, you'll want to verify that they own the new value before they can use it to sign in and receive messages. User pools have a configurable option that determines whether users must verify updates to their email address or phone number. @@ -384 +384 @@ If your user pool doesn’t require that users verify an updated email address o -If your user pool requires that users verify an updated email address or phone number, Amazon Cognito keeps the attribute verified and set to its original value until your user verifies the new attribute value. If the attribute is an alias for sign-in, your user can sign in with the original attribute value until verification changes the attribute to the new value. For more information about how to configure your user pool to require users to verify updated attributes, see [Configuring email or phone verification](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-email-phone-verification.html). +This option is the user pool property `AttributesRequireVerificationBeforeUpdate`. Configure it in a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-UserAttributeUpdateSettings) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-UserAttributeUpdateSettings) request, or with the setting **Keep original attribute value active when an update is pending** in the **Sign-up** menu of the Amazon Cognito console. @@ -386 +386,22 @@ If your user pool requires that users verify an updated email address or phone n -You can use a custom message Lambda trigger to customize the verification message. For more information, see [Custom message Lambda trigger](./user-pool-lambda-custom-message.html). When a user's email address or phone number is unverified, your app should inform the user that they must verify the attribute, and provide a button or link for users to verify their new email address or phone number. +How your user pool treats updates to email addresses and phone numbers is connected to the username configuration of your user pool. User pool usernames can be in a _username attributes_ configuration where sign-in names are email address, phone number, or both. They can also be in an _alias attributes_ configuration where the `username` attribute is a sign-in name along with email address, phone number, or preferred username as alternative sign-in names. For more information, see [Customizing sign-in attributes](./user-pool-settings-attributes.html#user-pool-settings-aliases). + +You can also use a custom message Lambda trigger to customize the verification message. For more information, see [Custom message Lambda trigger](./user-pool-lambda-custom-message.html). When a user's email address or phone number is unverified, your application should inform the user that they must verify the attribute, and provide a button or link for users to enter their verification code. + +The following table describes how `AttributesRequireVerificationBeforeUpdate` and alias settings determine the outcome when users change the value of their sign-in attributes. + +Username configuration | Behavior when users must verify new attributes | Behavior when users aren't required to verify new attributes +---|---|--- +Username attributes | Original attribute remains verified, eligible for sign-in, and at original value. When user verifies new value, Amazon Cognito updates the attribute value, marks it verified, and makes it eligible for sign-in. | Amazon Cognito updates attribute to new value. New value is eligible for sign-in. When user verifies new value, Amazon Cognito marks it as verified. +Alias attributes | Original attribute remains verified, eligible for sign-in, and at original value. When user verifies new value, Amazon Cognito updates the attribute value, marks it verified, and makes it eligible for sign-in. | Amazon Cognito updates attribute to new value. Neither original or new attribute value is eligible for sign-in. When user verifies new value, Amazon Cognito updates the attribute value, marks it verified, and makes it eligible for sign-in. + +###### Example 1 + +User 1 signs into your application with the email address `[email protected]` and has the username `user1` (alias attributes). Your user pool is configured to verify updates to sign-in attributes and to automatically send verification messages. They request to update their email address to `[email protected]`. They receive a verification email at `[email protected]` and _can sign in again_ only with the email address `[email protected]`. Later, they enter their verification code and can sign in again only with the email address `[email protected]`. + +###### Example 2 + +User 2 signs into your application with the email address `[email protected]` and has a username (alias attributes). Your user pool is configured _not_ to verify updates to sign-in attributes and to automatically send verification messages. They request to update their email address to `[email protected]`. They receive a verification email at `[email protected]` and _can't sign in again_. Later, they enter their verification code and can sign in again only with the email address `[email protected]`. + +###### Example 3 + +User 3 signs into your application with the email address `[email protected]` and doesn't have a username (username attributes). Your user pool is configured _not_ to verify updates to sign-in attributes and to automatically send verification messages. They request to update their email address to `[email protected]`. They receive a verification email at `[email protected]`, but they _can immediately sign in_ with no additional action taken with the verification code.