Cognito User Pool Email or Phone Number as Username

If you want your user to sign in using email addresses, you setup alias when creating your user pool.

Cognito will do the following.

  • During sign-up, treat your username parameter as an email, or a phone number and populate email or phone_number fields respectively
  • Internally, generates a UUID for username field, the same as sub claim
  • Allow user to sign in with their email or phone_number, which must be unique across the pool

CloudFormation Snippet

Confusion in names is typical in AWS. This feature is called “alias” in the docs, is an option in console, and is called “UsernameAttributes” in CloudFormation.

  UserPool:
    Type: AWS::Cognito::UserPool
    Properties:
      AutoVerifiedAttributes:
        - email
      UsernameAttributes:
        - email
      UsernameConfiguration:
        CaseSensitive: false