Standard attributes Username and preferred username Customizing sign-in attributes Custom attributes Attribute permissions and scopes

Working with user attributes

Attributes are pieces of information that help you identify individual users, such as name, email address, and phone number. A new user pool has a set of default standard attributes. You can also add custom attributes to your user pool definition in the AWS Management Console. This topic describes those attributes in detail and gives you tips on how to set up your user pool.

Don't store all information about your users in attributes. For example, keep user data that changes frequently, such as usage statistics or game scores, in a separate data store, such as Amazon Cognito Sync or Amazon DynamoDB.

Sanitize the inputs for user-attribute string values before you submit them to your user pool. One method to analyze proposed user attribute values is with a Lambda trigger like pre sign-up.

Note

Some documentation and standards refer to attributes as members.

Standard attributes

Amazon Cognito assigns all users a set of standard attributes based on the OpenID Connect specification. By default, standard and custom attribute values can be any string with a length of up to 2048 characters, but some attribute values have format restrictions.

The standard attributes are:

name
family_name
given_name
middle_name
nickname
preferred_username
profile
picture
website
gender
birthdate
zoneinfo
locale
updated_at
address
email
phone_number
sub

Except for sub, standard attributes are optional by default for all users. To make an attribute required, during the user pool creation process, select the Required check box next to the attribute. Amazon Cognito assigns a unique user identifier value to each user's sub attribute. Only the email and phone_number attributes can be verified.

Standard attributes have predefined properties that you can view in the SchemaAttributes parameter of a DescribeUserPool API response. You can set custom values for these attribute properties, like data type, mutability, and length constraints. To modify standard attribute properties, set their custom values in the CreateUserPool Schema parameter. The schema is also where you set required attributes. You can't modify the properties of standard attributes when you create user pools in the Amazon Cognito console.

Note

When you mark a standard attribute as Required, a user can't register unless they provide a value for the attribute. To create users and not give values for required attributes, administrators can use the AdminCreateUser API. After you create a user pool, you can't switch an attribute between required and not required.

Standard attribute details and format restrictions

birthdate

Value must be a valid 10 character date in the format YYYY-MM-DD.

email

Users and administrators can verify email address values.

An administrator with proper AWS account permissions can change the user's email address and also mark it as verified. Mark an email address as verified with the AdminUpdateUserAttributes API or the admin-update-user-attributes AWS Command Line Interface (AWS CLI) command. With this command, the administrator can change the email_verified attribute to true. You can also edit a user in the Users menu of the Amazon Cognito console to mark an email address as verified.

Value must be a valid email address string following the standard email format with @ symbol and domain, up to 2048 characters in length.

phone_number

A user must provide a phone number if SMS multi-factor authentication (MFA) is active. For more information, see Adding MFA to a user pool.

Users and administrators can verify phone number values.

An administrator with proper AWS account permissions can change the user's phone number and also mark it as verified. Mark a phone number as verified with the AdminUpdateUserAttributes API or the admin-update-user-attributes AWS CLI command. With this command, the administrator can change the phone_number_verified attribute to true. You can also edit a user in the Users menu of the Amazon Cognito console to mark a phone number as verified.

Important

Phone numbers must follow these format rules: A phone number must start with a plus (+) sign, followed immediately by the country code. A phone number can only contain the + sign and digits. Remove any other characters from a phone number, such as parentheses, spaces, or dashes (-) before you submit the value to the service. For example, a phone number based in the United States must follow this format: +14325551212.

preferred_username

You can select preferred_username as required or as an alias, but not both. If the preferred_username is an alias, you can make a request to the UpdateUserAttributes API operation and add the attribute value after you confirm the user.

sub

Index and search your users based on the sub attribute. The sub attribute is a unique user identifier within each user pool. Users can change attributes like phone_number and email. The sub attribute has a fixed value. For more information about finding users, see Managing and searching for user accounts.

Important

Amazon Cognito generates sub in an Amazon Cognito-specific format that doesn't conform to a specific UUID format, including RFC UUID. You shouldn't strictly validate the format of sub.

View required attributes

Use the following procedure to view required attributes for a given user pool.

Note

You can't change required attributes after you create a user pool.

To view required attributes

Go to Amazon Cognito in the AWS Management Console. If the console prompts you, enter your AWS credentials.
Choose User Pools.
Choose an existing user pool from the list.
Choose the Sign-up menu.
In the Required attributes section, view the required attributes of your user pool.

Username and preferred username

The username value is a separate attribute and not the same as the name attribute. Each user has a username attribute. Amazon Cognito automatically generates a username for federated users. You must provide a username attribute to create a local user in the Amazon Cognito directory. After you create a user, you can't change the value of the username attribute.

Developers can use the preferred_username attribute to give users usernames that they can change. For more information, see Customizing sign-in attributes.

If your application doesn't require a username, you don't need to ask users to provide one. Your app can create a unique username for users in the background. This can be useful if you want users to register and sign in with an email address and password. For more information, see Customizing sign-in attributes.

The username must be unique within a user pool. A username can be reused, but only after you delete it and it is no longer in use. For information about the string constraints to the username attributes, see the username property of a SignUp API request.

Customizing sign-in attributes

When you create a user pool, you can set up username attributes if you want your users to be able to sign up and sign in with an email address or phone number as their username. Alternatively, you can set up alias attributes to give your users the option: they can include multiple attributes when they sign up, and then sign in with a username, preferred username, email address, or phone number.

Important

After you create a user pool, you can't change this setting.

How to choose between alias attributes and username attributes

Your requirement	Alias attributes	Username attributes
Users have multiple sign-in attributes	Yes¹	No²
Users must verify email address or phone number before they can sign in with it	Yes	No
Sign up users with duplicate email addresses or phone numbers and prevent `UsernameExistsException` errors³