User pool case sensitivity

Amazon Cognito user pools that you create in the AWS Management Console are case insensitive by default. When a user pool is case insensitive, [e-mail] and [e-mail] refer to the same user. When usernames in a user pool are case insensitive, the preferred_username and email attributes also are case insensitive.

To account for user pool case sensitivity settings, identify users in your app code based on an alternative user attribute. Because the case of a username, preferred username, or email address attribute can vary in different user profiles, refer instead to the sub attribute. You can also create an immutable custom attribute in your user pool, and assign your own unique identifier value to the attribute in each new user profile. When you first create a user, you can write a value to the immutable custom attribute that you created.

Note

Regardless of the case sensitivity settings of your user pool, Amazon Cognito requires that a federated user from a SAML or OIDC identity provider (IdP) pass a unique and case-sensitive NameId or sub claim. For more information about unique identifier case sensitivity and SAML IdPs, see SAML user pool SP-initiated sign-in flow.

Creating a case-sensitive user pool

If you create resources with the AWS Command Line Interface (AWS CLI) and API operations such as CreateUserPool, you must set the Boolean CaseSensitive parameter to false. This setting creates a case-insensitive user pool. If you do not specify a value, CaseSensitive defaults to true. This default is the opposite of the default behavior for user pools that you create in the AWS Management Console. Before February 12, 2020, user pools defaulted to case sensitive regardless of platform.

You can use the Sign-in experience tab of the AWS Management Console or the DescribeUserPool API operation to review the case sensitivity settings for each user pool in your account.

Migrating to a new user pool

Because of potential conflicts between user profiles, you can't change an Amazon Cognito user pool from case-sensitive to case-insensitive. Instead, migrate your users to a new user pool. You must build migration code to resolve case-related conflicts. This code must either return a unique new user or reject the sign-in attempt when it detects a conflict. In a new case-insensitive user pool, assign a Migrate user Lambda trigger. The AWS Lambda function can create users in the new case-insensitive user pool. When the user fails sign-in with the case-insensitive user pool, the Lambda function finds and duplicates the user from the case-sensitive user pool. You can also activate a migrate user Lambda trigger on ForgotPassword events. Amazon Cognito passes user information and event metadata from the sign-in or password-recovery action to your Lambda function. You can use event data to manage conflicts between usernames and email addresses when your function creates the new user in your case-insensitive user pool. These conflicts are between usernames and email addresses that would be unique in a case-insensitive user pool, but identical in a case-sensitive user pool.

For more information about how to use a migrate user Lambda trigger between Amazon Cognito user pools, see Migrating Users to Amazon Cognito user pools in the AWS blog.