How do I troubleshoot issues with an Amazon Cognito user's email_verified attribute?

Last updated: 2023-01-18

I want to resolve any issues with the email_verified attribute for Amazon Cognito users.

Short description

An Amazon Cognito user pool has a set of standard attributes that are used to identify individual users. The email_verified attribute that indicates whether a user's email address has been verified can change in the following situations:

  • A user updates their email address. When a user updates their email address, Amazon Cognito changes the email_verified attribute to unverified.
  • An email address is configured as an alias. Then, a user with a duplicate email address is created. When an email address is set as an alias, only one user can hold the email address value as the email_verified attribute. If the newer user's account confirmation succeeds, then the email address alias is transferred to the newer user. The former user's email address is then unverified. For more information, see User pool attributes and review the Customizing sign-in attributes section.
  • A federated user or a user linked to a federated user signs in with an email mapping. When a federated user signs in, a mapping must be present for each user pool attribute that your user pool requires. If an email attribute is mapped, the email_verified attribute changes to unverified by default.

Resolution

To resolve issues with the email_verified attribute, follow the steps that apply to your situation.

Important: In the following example AWS Command Line Interface (AWS CLI) commands, replace all instances of example strings with your values. (For example, replace "example_access_token" with your access token value.)

Verification after an email address update

To verify the email address after a user update:

1.    For Amazon Cognito to send the verification code to an updated email address, configure the email verification setting for the user pool.

2.    If necessary, update the email address by calling the UpdateUserAttributes API or the AdminUpdateUserAttributes API.

An example update-user-attributes command:

aws cognito-idp update-user-attributes --access-token "example_access_token" --user-attributes Name="email",Value="example_new_email"

An example admin-update-user-attributes command:

aws cognito-idp admin-update-user-attributes --user-pool-id "example_user_pool_id" --username "example_username" --user-attributes Name="email",Value="example_new_email"

Important: The AdminUpdateUserAttributes API can also be used to automatically verify the email by setting the email_verified attribute to True. If the email address is automatically verified with the AdminUpdateUserAttributes API, the next step isn't necessary. The next step is necessary when using the UpdateUserAttributes API.

3.    Check your new email inbox for the verification code.

4.    Call the VerifyUserAttribute API. Specify the parameters for AccessToken and AttributeName as "email" and enter the verification code from the previous step.

An example verify-user-attribute command:

aws cognito-idp verify-user-attribute --access-token "example_access_token" --attribute-name "email" --code "example_verification_code"

To verify the email address after the initial code expires:

1.    Sign in to your application with your user name to retrieve your access token.

2.    Call the GetUserAttributeVerificationCode API. Set the AttributeName parameter as "email".

An example get-user-attribute-verification-code command:

aws cognito-idp get-user-attribute-verification-code --access-token "example_access_token" --attribute-name "email"

3.    Call the VerifyUserAttribute API. Specify the parameters for AccessToken and AttributeName as "email". Enter the verification code from the previous step.

Confirm a new user with a duplicate email address

To allow the confirmation of a new user with a duplicate email address:

1.    If necessary, call the SignUp API to sign up a user with a configured email address.

An example sign-up command:

aws cognito-idp sign-up --client-id "example_client_id" --username "example_username" --password "example_password" --user-attributes Name="email",Value="example_user_email"

2.    Call the ConfirmSignUp API with the ForceAliasCreation parameter set to True.

An example confirm-sign-up command:

aws cognito-idp confirm-sign-up --client-id "example_client_id" --username "example_username" --confirmation-code "example_confirmation_code" --force-alias-creation

To deny the confirmation of a new user with a duplicate email address after sign up:

1.    Call the ConfirmSignUp API with the ForceAliasCreation parameter set to False.

Note: ForceAliasCreation is False by default. Therefore, it's not required to be passed as a parameter in the request.

An example deny-sign-up command:

aws cognito-idp confirm-sign-up --client-id "example_client_id" --username "example_username" --confirmation-code "example_confirmation_code" --no-force-alias-creation

2.    By setting the ForceAliasCreation parameter to False, the API returns the following error:

An error occurred (AliasExistsException) when calling the ConfirmSignUp operation: An account with the email already exists.

Create a new user with a duplicate email address as an administrator

To create a new user with a duplicate email address as an administrator:

1.    Call the AdminCreateUser API with a configured email address, with the email_verified attribute set to True and the ForceAliasCreation parameter set to True.

An example admin-create-user command:

aws cognito-idp admin-create-user --user-pool-id "example_user_pool_id" --username "example_username" --user-attributes Name="email",Value="example_user_email" Name="email_verified",Value="True" --force-alias-creation

Map the email_verified attribute to a third-party identity provider (IdP)

To keep the email_verified attribute verified after federation:

1.    From the Amazon Cognito console, map the IdP attribute for verification status to the email_verified attribute.

Note: Most OpenID Connect (OIDC) providers include the email_verified attribute.


Did this article help?


Do you need billing or technical support?