# Managing users in your user pool
After you create a user pool, you can create, confirm, and manage user accounts. With Amazon Cognito user pools groups you can manage your users and their access to resources by mapping IAM roles to groups.
Managing users in your Amazon Cognito user pool involves a variety of configuration options and administrative tasks. User pools can scale to millions of users. A user directory of this scale requires equally scalable and repeatable administrative tools. You might want to create many user profiles, manage inactive users, produce governance and compliance reports, or set up self-service tools where users do most of the work. After you create a user pool, you can control how users sign up and confirm their accounts, including requiring email or phone number verification. Administrators can also create user accounts directly and customize the welcome messages and password requirements.
User pools have user groups, where you can manage access to resources based on a user's group membership. You can assign IAM roles to these groups to manage access to AWS services with identity pools. Users' group membership is present in both ID and access tokens. With this information, you can make access-control decisions at runtime in your application or with a policy engine like Amazon Verified Permissions.
User pools often have many users. You will frequently find yourself searching for and updating user accounts. The Amazon Cognito console and API support querying users based on standard attributes like username, email, and phone number. Administrators can also reset passwords, disable accounts, and view user event history.
For migrating existing user data, Amazon Cognito has options to import users from a CSV file and to use a [Lambda trigger](user-pool-lambda-migrate-user.md) to automatically migrate users when they first sign in. These options support user transitions from other user directories to your user pool.
You can use the user-management features in user pools to have fine-grained control over the user lifecycle and authentication experience. The combination of self-service sign-up, admin-created accounts, groups, and migration tools makes Amazon Cognito user pools a flexible user directory.
**Topics**
+ [Configuring policies for user creation](user-pool-settings-admin-create-user-policy.md)
+ [Signing up and confirming user accounts](signing-up-users-in-your-app.md)
+ [Creating user accounts as administrator](how-to-create-user-accounts.md)
+ [Adding groups to a user pool](cognito-user-pools-user-groups.md)
+ [Managing and searching for user accounts](how-to-manage-user-accounts.md)
+ [Passwords, account recovery, and password policies](managing-users-passwords.md)
+ [Importing users into a user pool](cognito-user-pools-import-users.md)
+ [Working with user attributes](user-pool-settings-attributes.md)
# Configuring policies for user creation
Your user pool can allow users to sign up, or you can create them as an administrator. You can also control how much of the process of verification and confirmation after sign-up is in the hands of your users. For example, you might want to review sign-ups and accept them based on an external validation process. This configuration, or *admin create user policy*, also sets the amount of time before a user can no longer confirm their user account.
Amazon Cognito can serve the needs of your public customers as the customer identity and access management (CIAM) platform for your software. A user pool that accepts sign-up and has an app client, with or without managed login, creates a user profile for anyone on the internet who knows your publicly-discoverable app client ID and requests to sign up. A signed-up user profile can receive access and identity tokens and can access resources that you've authorized for your app. Before you activate sign-up in your user pool, review your options and ensure that your configuration complies with your security standards. Set **Enable self-registration** and `AllowAdminCreateUserOnly`, described in the following procedures, with care.
------
#### [ AWS Management Console ]
The **Sign-up** menu of your user pool contains some of the settings for sign-up and administrative creation of users in your user pool.
**To configure the sign-up experience**
1. In **Cognito-assisted verification and confirmation**, choose whether you want to **Allow Cognito to automatically send messages to verify and confirm**. With this setting enabled, Amazon Cognito sends an email or SMS message to new users with a code that they must present to your user pool. This confirms their ownership of the email address or phone number, setting the equivalent attribute as verified and confirming the user account for sign-in. The **Attributes to verify** that you choose determine the delivery methods and destinations of the verification messages.
1. **Verifying attribute changes** isn't significant when you're creating users, but relates to attribute verification. You can permit users who have changed but not yet verified their [sign-in attributes](user-pool-settings-attributes.md#user-pool-settings-aliases.title) to continue to sign in either with their new attribute value or with their original. For more information, see [Verifying when users change their email or phone number](signing-up-users-in-your-app.md#verifying-when-users-change-their-email-or-phone-number).
1. **Required attributes** displays the attributes that must be provided a value before a user can sign up or you can create a user. You can only set required attributes when you create a user pool.
1. **Custom attributes** are important to the user creation and sign-up process because you can only set a value for *immutable* custom attributes when you first create a user. For more information about custom attributes, see [Custom attributes](user-pool-settings-attributes.md#user-pool-settings-custom-attributes).
1. In **Self-service sign-up**, select **Enable self-registration** if you want users to be able to generate a new account with the [unauthenticated](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html#user-pool-apis-auth-unauth) `SignUp` API. If you disable self-registration, you can only create new users as an administrator, in the Amazon Cognito console or with [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html) API requests. In a user pool where self-registration is inactive, [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) API requests return `NotAuthorizedException` and managed login doesn't display a **Sign up** link.
For user pools where you plan to create users as an administrator, you can configure the duration of their temporary passwords in the setting in the **Authentication methods** menu under **Temporary passwords set by administrators expire in**.
Another important element of the creation of users as an administrator is the invitation message. When you create a new user, Amazon Cognito sends them a message with a link to your app so that they can sign in for the first time. Customize this message template in the **Authentication methods** menu under **Message templates**.
You can configure [confidential app clients](user-pool-settings-client-apps.md#user-pool-settings-client-app-client-types.title), typically web applications, with a client secret that prevents sign-up without the app client secret. As a security best practice, do not distribute app client secrets in public app clients, typically mobile apps. You can create app clients with client secrets in the **App clients** menu of the Amazon Cognito console.
------
#### [ Amazon Cognito user pools API ]
You can programmatically set the parameters for creation of users in a user pool in a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API request.
The [AdminCreateUserConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-AdminCreateUserConfig) element sets values for the following properties of a user pool.
1. Enable self-service sign-up
1. The invitation message that you send to new admin-created users
The following example, when added to a full API request body, sets a user pool with self-service sign-up inactive and a basic invitation email.
```
"AdminCreateUserConfig": {
"AllowAdminCreateUserOnly": true,
"InviteMessageTemplate": {
"EmailMessage": "Your username is {username} and temporary password is {####}.",
"EmailSubject": "Welcome to ExampleApp",
"SMSMessage": "Your username is {username} and temporary password is {####}."
}
}
```
The following additional parameters of a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API request govern the creation of new users.
[AutoVerifiedAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-AutoVerifiedAttributes)
The attributes, email addresses or phone numbers, that you want to [automatically send a message to](user-pool-settings-email-phone-verification.md#user-pool-settings-email-phone-verification.title) when you register a new user.
[Policies](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Policies)
The user pool [password policy](managing-users-passwords.md#user-pool-settings-policies.title).
[Schema](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Schema)
The user pool [custom attributes](user-pool-settings-attributes.md#user-pool-settings-custom-attributes.title). They are important to the user creation and sign-up process because you can only set a value for *immutable* custom attributes when you first create a user.
This parameter also sets the required attributes for your user pool. The following text, when inserted into the `Schema` element of a full API request body, set the `email` attribute as required.
```
{
"Name": "email",
"Required": true
}
```
------
# Signing up and confirming user accounts
User accounts are added to your user pool in one of the following ways:
+ The user signs up in your user pool's client app. This can be a mobile or web app.
+ You can import the user's account into your user pool. For more information, see [Importing users into user pools from a CSV file](cognito-user-pools-using-import-tool.md).
+ You can create the user's account in your user pool and invite the user to sign in. For more information, see [Creating user accounts as administrator](how-to-create-user-accounts.md).
Users who sign themselves up must be confirmed before they can sign in. Imported and created users are already confirmed, but they must create their password the first time they sign in. The following sections explain the confirmation process and email and phone verification.
**Passwords at sign-up**
Amazon Cognito requires passwords from all users when they sign up, except under the following conditions. If *all* of these conditions are met, you can omit passwords in sign-up operations.
1. [Passwordless sign-in](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless) is active in your user pool and app client.
1. Your application is custom-built with authentication modules in an AWS SDK. Managed login and the hosted UI always require passwords.
1. Users provide attribute values for the passwordless sign-in methods—email or SMS message one-time passwords (OTPs)—that you permit. For example, if you allow sign-in with email and phone OTP, users can provide either a phone number or email address, but if you only allow sign-in with email, they must provide an email address.
1. Your user pool [automatically verifies](#allowing-users-to-sign-up-and-confirm-themselves) the attributes that users can use with passwordless sign-in.
1. For any given [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) request, the user doesn't provide a value for the [Password](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Password) parameter.
## Overview of user account confirmation
The following diagram illustrates the confirmation process:
![\[When users enter the confirmation code, they automatically verify email or phone.\]](http://docs.aws.amazon.com/cognito/latest/developerguide/images/amazon-cognito-sign-in-confirm-user.png)
A user account can be in any of the following states:
**Registered (Unconfirmed)**
The user has successfully signed up, but cannot sign in until the user account is confirmed. The user is enabled but not confirmed in this state.
New users who sign themselves up start in this state.
**Confirmed**
The user account is confirmed and the user can sign in. When a user enters a code or follows an email link to confirm their user account, that email or phone number is automatically verified. The code or link is valid for 24 hours.
If the user account was confirmed by the administrator or a pre sign-up Lambda trigger, there might not be a verified email or phone number associated with the account.
**Password Reset Required**
The user account is confirmed, but the user must request a code and reset their password before they can sign in.
User accounts that are imported by an administrator or developer start in this state.
**Force Change Password**
The user account is confirmed and the user can sign in using a temporary password, but on first sign-in, the user must change their password to a new value before doing anything else.
User accounts that are created by an administrator or developer start in this state.
**Disabled**
Before you can delete a user account, you must disable sign-in access for that user.
**More resources**
+ [Detecting and remediating inactive user accounts with Amazon Cognito](https://aws.amazon.com/blogs/security/detecting-and-remediating-inactive-user-accounts-with-amazon-cognito/)
## Verifying contact information at sign-up
When new users sign up in your app, you probably want them to provide at least one contact method. For example, with your users' contact information, you might:
+ Send a temporary password when a user chooses to reset their password.
+ Notify users when their personal or financial information is updated.
+ Send promotional messages, such as special offers or discounts.
+ Send account summaries or billing reminders.
For use cases like these, it's important that you send your messages to a verified destination. Otherwise, you might send your messages to an invalid email address or phone number that was typed incorrectly. Or worse, you might send sensitive information to bad actors who pose as your users.
To help ensure that you send messages only to the right individuals, configure your Amazon Cognito user pool so that users must provide the following when they sign up:
1. An email address or phone number.
1. A verification code that Amazon Cognito sends to that email address or phone number. If 24 hours have passed and your user's code or link is no longer valid, call the [ResendConfirmationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html) API operation to generate and send a new code or link.
By providing the verification code, a user proves that they have access to the mailbox or phone that received the code. After the user provides the code, Amazon Cognito updates the information about the user in your user pool by:
+ Setting the user's status to `CONFIRMED`.
+ Updating the user's attributes to indicate that the email address or phone number is verified.
To view this information, you can use the Amazon Cognito console. Or, you can use the `AdminGetUser` API operation, the `admin-get-user` command with the AWS CLI, or a corresponding action in one of the AWS SDKs.
If a user has a verified contact method, Amazon Cognito automatically sends a message to the user when the user requests a password reset.
### Other actions that confirm and verify user attributes
The following user activity verifies user attributes. You're not required to set these attributes to automatically verify: the listed actions mark them as verified in all cases.
**Email address**
1. Successfully completing [passwordless authentication](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless) with an email one-time password (OTP).
1. Successfully completing [multi-factor authentication (MFA)](user-pool-settings-mfa.md) with an email OTP.
**Phone number**
1. Successfully completing [passwordless authentication](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless) with an SMS OTP.
1. Successfully completing [MFA](user-pool-settings-mfa.md) with an SMS OTP.
### To configure your user pool to require email or phone verification
When you verify your users' email addresses and phone numbers, you ensure that you can contact your users. Complete the following steps in the AWS Management Console to configure your user pool to require that your users confirm their email addresses or phone numbers.
**Note**
If you don't yet have a user pool in your account, see [Getting started with user pools](getting-started-user-pools.md).
**To configure your user pool**
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. From the navigation pane, choose **User Pools**. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Sign-up** menu and locate **Attribute verification and user account confirmation**. Choose **Edit**.
1. Under **Cognito-assisted verification and confirmation**, choose whether you will **Allow Cognito to automatically send messages to verify and confirm**. With this setting enabled, Amazon Cognito sends messages to the user contact attributes you choose when a user signs up, or you create a user profile. To verify attributes and confirm user profiles for sign-in, Amazon Cognito sends a code or link in messages to users. The users must then enter the code in your UI so that your app can confirm them in a `ConfirmSignUp` or `AdminConfirmSignUp` API request.
**Note**
You can also disable **Cognito-assisted verification and confirmation** and use authenticated API actions or Lambda triggers to verify attributes and confirm users.
If you choose this option, Amazon Cognito doesn't send verification codes when users sign up. Choose this option if you are using a custom authentication flow that verifies at least one contact method without using verification codes from Amazon Cognito. For example, you might use a pre sign-up Lambda trigger that automatically verifies email addresses that belong to a specific domain.
If you don't verify your users' contact information, they may be unable to use your app. Remember that users require verified contact information to:
**Reset their passwords** — When a user chooses an option in your app that calls the `ForgotPassword` API action, Amazon Cognito sends a temporary password to the user's email address or phone number. Amazon Cognito sends this password only if the user has at least one verified contact method.
**Sign in by using an email address or phone number as an alias** — If you configure your user pool to allow these aliases, then a user can sign in with an alias only if the alias is verified. For more information, see [Customizing sign-in attributes](user-pool-settings-attributes.md#user-pool-settings-aliases).
1. Choose your **Attributes to verify**:
**Send SMS message, verify phone number**
Amazon Cognito sends a verification code in an SMS message when the user signs up. Choose this option if you typically communicate with your users through SMS messages. For example, you will want to use verified phone numbers if you send delivery notifications, appointment confirmations, or alerts. User phone numbers will be the verified attribute when accounts are confirmed; you must take additional action to verify and communicate with user email addresses.
**Send email message, verify email address**
Amazon Cognito sends a verification code through an email message when the user signs up. Choose this option if you typically communicate with your users through email. For example, you will want to use verified email addresses if you send billing statements, order summaries, or special offers. User email addresses will be the verified attribute when accounts are confirmed; you must take additional action to verify and communicate with user phone numbers.
**Send SMS message if phone number is available, otherwise send email message**
Choose this option if you don't require all users to have the same verified contact method. In this case, the sign-up page in your app could ask users to verify only their preferred contact method. When Amazon Cognito sends a verification code, it sends the code to the contact method provided in the `SignUp` request from your app. If a user provides both an email address and a phone number, and your app provides both contact methods in the `SignUp` request, Amazon Cognito sends a verification code only to the phone number.
If you require users to verify both an email address and a phone number, choose this option. Amazon Cognito verifies one contact method when the user signs up, and your app must verify the other contact method after the user signs in. For more information, see [If you require users to confirm both email addresses and phone numbers](#verification-email-plus-phone).
1. Choose **Save changes**.
### Authentication flow with email or phone verification
If your user pool requires users to verify their contact information, your app must facilitate the following flow when a user signs up:
1. A user signs up in your app by entering a username, phone number and/or email address, and possibly other attributes.
1. The Amazon Cognito service receives the sign-up request from the app. After verifying that the request contains all attributes required for sign-up, the service completes the sign-up process and sends a confirmation code to the user's phone (in an SMS message) or email. The code is valid for 24 hours.
1. The service returns to the app that sign-up is complete and that the user account is pending confirmation. The response contains information about where the confirmation code was sent. At this point the user's account is in an unconfirmed state, and the user's email address and phone number are unverified.
1. The app can now prompt the user to enter the confirmation code. It is not necessary for the user to enter the code immediately. However, the user will not be able to sign in until after they enter the confirmation code.
1. The user enters the confirmation code in the app.
1. The app calls [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html) to send the code to the Amazon Cognito service, which verifies the code and, if the code is correct, sets the user's account to the confirmed state. After successfully confirming the user account, the Amazon Cognito service automatically marks the attribute that was used to confirm (email address or phone number) as verified. Unless the value of this attribute is changed, the user will not have to verify it again.
1. At this point the user's account is in a confirmed state, and the user can sign in.
### If you require users to confirm both email addresses and phone numbers
Amazon Cognito verifies only one contact method when a user signs up. In cases where Amazon Cognito must choose between verifying an email address or phone number, it chooses to verify the phone number by sending a verification code through SMS message. For example, if you configure your user pool to allow users to verify either email addresses or phone numbers, and if your app provides both of these attributes upon sign-up, Amazon Cognito verifies only the phone number. After a user verifies their phone number, Amazon Cognito sets the user's status to `CONFIRMED`, and the user is allowed to sign in to your app.
After the user signs in, your app can provide the option to verify the contact method that wasn't verified during sign-up. To verify this second method, your app calls the `VerifyUserAttribute` API action. Note that this action requires an `AccessToken` parameter, and Amazon Cognito only provides access tokens for authenticated users. Therefore, you can verify the second contact method only after the user signs in.
If you require your users to verify both email addresses and phone numbers, do the following:
1. Configure your user pool to allow users to verify email address or phone numbers.
1. In the sign-up flow for your app, require users to provide both an email address and a phone number. Call the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) API action, and provide the email address and phone number for the `UserAttributes` parameter. At this point, Amazon Cognito sends a verification code to the user's phone.
1. In your app interface, present a confirmation page where the user enters the verification code. Confirm the user by calling the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html) API action. At this point, the user's status is `CONFIRMED`, and the user's phone number is verified, but the email address is not verified.
1. Present the sign-in page, and authenticate the user by calling the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API action. After the user is authenticated, Amazon Cognito returns an access token to your app.
1. Call the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html) API action. Specify the following parameters in the request:
+ `AccessToken` – The access token returned by Amazon Cognito when the user signed in.
+ `AttributeName` – Specify `"email"` as the attribute value.
Amazon Cognito sends a verification code to the user's email address.
1. Present a confirmation page where the user enters the verification code. When the user submits the code, call the [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) API action. Specify the following parameters in the request:
+ `AccessToken` – The access token returned by Amazon Cognito when the user signed in.
+ `AttributeName` – Specify `"email"` as the attribute value.
+ `Code` – The verification code that the user provided.
At this point, the email address is verified.
## Allowing users to sign up in your app but confirming them as a user pool administrator
You might not want your user pool to automatically send verification messages in your user pool, but still want to allow anyone to sign up for an account. This model leaves room, for example, for human review of new sign-up requests, and for batch validation and processing of sign-ups. You can confirm new user accounts in the Amazon Cognito console or with the IAM-authenticated API operation [AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html). You can confirm user accounts as an administrator whether or not your user pool sends verification messages.
You can only confirm a user self-service sign-up with this technique. To confirm a user that you create as an administrator, create an [AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API request with `Permanent` set to `True`.
1. A user signs up in your app by entering a username, phone number and/or email address, and possibly other attributes.
1. The Amazon Cognito service receives the sign-up request from the app. After verifying that the request contains all attributes required for sign-up, the service completes the sign-up process and returns to the app that sign-up is complete, pending confirmation. At this point the user's account is in an unconfirmed state. The user cannot sign in until the account is confirmed.
1. Confirm the user's account. You must sign in to the AWS Management Console or sign your API request with AWS credentials to confirm the account.
1. To confirm a user in the Amazon Cognito console, navigate to the **Users** menu, choose the user who you want to confirm, and from the **Actions** menu select **Confirm**.
1. To confirm a user in the AWS API or CLI, create a [AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html) API request, or [admin-confirm-sign-up](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-confirm-sign-up.html) in the AWS CLI.
1. At this point the user's account is in a confirmed state, and the user can sign in.
## Computing secret hash values
Assign a client secret to your confidential app client as a best practice. When you assign a client secret to your app client, your Amazon Cognito user pools API requests must include a hash that includes the client secret in the request body. To validate your knowledge of the client secret for the API operations in the following lists, concatenate the client secret with your app client ID and your user's username, then base64-encode that string.
When your app signs in users to a client that has a secret hash, you can use the value of any user pool sign-in attribute as the username element of the secret hash. When your app requests new tokens in an authentication operation with `REFRESH_TOKEN_AUTH`, the value of the username element depends on your sign-in attributes. When your user pool doesn’t have `username` as a sign-in attribute, set the secret hash username value from the user’s `sub` claim from their access or ID token. When `username` is a sign-in attribute, set the secret hash username value from the `username` claim.
The following Amazon Cognito user pools APIs accept a client-secret hash value in a `SecretHash` parameter.
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html)
Additionally, the following APIs accept a client-secret hash value in a `SECRET_HASH` parameter, either in authentication parameters or in a challenge response.
| API operation | Parent parameter for SECRET\$1HASH |
| --- |--- |
| InitiateAuth | AuthParameters |
| AdminInitiateAuth | AuthParameters |
| RespondToAuthChallenge | ChallengeResponses |
| AdminRespondToAuthChallenge | ChallengeResponses |
The secret hash value is a Base 64-encoded keyed-hash message authentication code (HMAC) calculated using the secret key of a user pool client and username plus the client ID in the message. The following pseudocode shows how this value is calculated. In this pseudocode, `+` indicates concatenation, `HMAC_SHA256` represents a function that produces an HMAC value using HmacSHA256, and `Base64` represents a function that produces Base-64-encoded version of the hash output.
```
Base64 ( HMAC_SHA256 ( "Client Secret Key", "Username" + "Client Id" ) )
```
For a detailed overview of how to calculate and use the `SecretHash` parameter, see [How do I troubleshoot "Unable to verify secret hash for client " errors from my Amazon Cognito user pools API?](https://aws.amazon.com/premiumsupport/knowledge-center/cognito-unable-to-verify-secret-hash/) in the AWS Knowledge Center.
You can use the following code examples in your server-side app code.
------
#### [ Shell ]
```
echo -n "[username][app client ID]" | openssl dgst -sha256 -hmac [app client secret] -binary | openssl enc -base64
```
------
#### [ Java ]
```
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public static String calculateSecretHash(String userPoolClientId, String userPoolClientSecret, String userName) {
final String HMAC_SHA256_ALGORITHM = "HmacSHA256";
SecretKeySpec signingKey = new SecretKeySpec(
userPoolClientSecret.getBytes(StandardCharsets.UTF_8),
HMAC_SHA256_ALGORITHM);
try {
Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);
mac.init(signingKey);
mac.update(userName.getBytes(StandardCharsets.UTF_8));
byte[] rawHmac = mac.doFinal(userPoolClientId.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(rawHmac);
} catch (Exception e) {
throw new RuntimeException("Error while calculating ");
}
}
```
------
#### [ Python ]
```
import sys
import hmac, hashlib, base64
username = sys.argv[1]
app_client_id = sys.argv[2]
key = sys.argv[3]
message = bytes(sys.argv[1]+sys.argv[2],'utf-8')
key = bytes(sys.argv[3],'utf-8')
secret_hash = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest()).decode()
print("SECRET HASH:",secret_hash)
```
------
## Confirming user accounts without verifying email or phone number
The pre sign-up Lambda trigger can be used to auto-confirm user accounts at sign-up, without requiring a confirmation code or verifying email or phone number. Users who are confirmed this way can immediately sign in without having to receive a code.
You can also mark a user's email or phone number verified through this trigger.
**Note**
While this approach is convenient for users when they're getting started, we recommend auto-verifying at least one of email or phone number. Otherwise the user can be left unable to recover if they forget their password.
If you don't require the user to receive and enter a confirmation code at sign-up and you don't auto-verify email and phone number in the pre sign-up Lambda trigger, you risk not having a verified email address or phone number for that user account. The user can verify the email address or phone number at a later time. However, if the user forgets his or her password and doesn't have a verified email address or phone number, the user is locked out of the account, because the forgot-password flow requires a verified email or phone number in order to send a verification code to the user.
## Verifying when users change their email or phone number
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.md).
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.
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.
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.md#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.md). 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 `user1@example.com` 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 `user1+foo@example.com`. They receive a verification email at `user1+foo@example.com` and *can sign in again* only with the email address `user1@example.com`. Later, they enter their verification code and can sign in again only with the email address `user1+foo@example.com`.
**Example 2**
User 2 signs into your application with the email address `user2@example.com` 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 `user2+bar@example.com`. They receive a verification email at `user2+bar@example.com` and *can't sign in again*. Later, they enter their verification code and can sign in again only with the email address `user2+bar@example.com`.
**Example 3**
User 3 signs into your application with the email address `user3@example.com` 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 `user3+baz@example.com`. They receive a verification email at `user3+baz@example.com`, but they *can immediately sign in* with no additional action taken with the verification code.
## Confirmation and verification processes for user accounts created by administrators or developers
User accounts that are created by an administrator or developer are already in the confirmed state, so users aren't required to enter a confirmation code. The invitation message that the Amazon Cognito service sends to these users includes the username and a temporary password. The user is required to change the password before signing in. For more information, see the [Customize email and SMS messages](how-to-create-user-accounts.md#creating-a-new-user-customize-messages) in [Creating user accounts as administrator](how-to-create-user-accounts.md) and the Custom Message trigger in [Customizing user pool workflows with Lambda triggers](cognito-user-pools-working-with-lambda-triggers.md).
## Confirmation and verification processes for imported user accounts
User accounts that are created by using the user import feature in the AWS Management Console, CLI, or API (see [Importing users into user pools from a CSV file](cognito-user-pools-using-import-tool.md)) are already in the confirmed state, so users aren't required to enter a confirmation code. No invitation message is sent. However, imported user accounts require users to first request a code by calling the `ForgotPassword` API and then create a password using the delivered code by calling `ConfirmForgotPassword` API before they sign in. For more information, see [Requiring imported users to reset their passwords](cognito-user-pools-using-import-tool.md#cognito-user-pools-using-import-tool-password-reset).
Either the user's email or phone number must be marked as verified when the user account is imported, so no verification is required when the user signs in.
## Sending emails while testing your app
Amazon Cognito sends email messages to your users when they create and manage their accounts in the client app for your user pool. If you configure your user pool to require email verification, Amazon Cognito sends an email when:
+ A user signs up.
+ A user updates their email address.
+ A user performs an action that calls the `ForgotPassword` API action.
+ You create a user account as an administrator.
Depending on the action that initiates the email, the email contains a verification code or a temporary password. Your users must receive these emails and understand the message. Otherwise, they might be unable to sign in and use your app.
To ensure that emails send successfully and that the message looks correct, test the actions in your app that initiate email deliveries from Amazon Cognito. For example, by using the sign-up page in your app, or by using the `SignUp` API action, you can initiate an email by signing up with a test email address. When you test in this way, remember the following:
**Important**
When you use an email address to test actions that initiate emails from Amazon Cognito, don't use a fake email address (one that has no mailbox). Use a real email address that will receive the email from Amazon Cognito without creating a *hard bounce*.
A hard bounce occurs when Amazon Cognito fails to deliver the email to the recipient's mailbox, which always happens if the mailbox doesn't exist.
Amazon Cognito limits the number of emails that can be sent by AWS accounts that persistently incur hard bounces.
When you test actions that initiate emails, use one of the following email addresses to prevent hard bounces:
+ An address for an email account that you own and use for testing. When you use your own email address, you receive the email that Amazon Cognito sends. With this email, you can use the verification code to test the sign-up experience in your app. If you customized the email message for your user pool, you can check that your customizations look correct.
+ The mailbox simulator address, *success@simulator.amazonses.com*. If you use the simulator address, Amazon Cognito sends the email successfully, but you're not able to view it. This option is useful when you don't need to use the verification code and you don't need to check the email message.
+ The mailbox simulator address with the addition of an arbitrary label, such as *success\$1user1@simulator.amazonses.com* or *success\$1user2@simulator.amazonses.com*. Amazon Cognito emails these addresses successfully, but you're not able to view the emails that it sends. This option is useful when you want to test the sign-up process by adding multiple test users to your user pool, and each test user has a unique email address.
# Configuring email or phone verification
You can choose settings for email or phone verification under the **Authentication methods** menu. For more information on multi-factor authentication (MFA), see [SMS Text Message MFA](user-pool-settings-mfa-sms-email-message.md).
Amazon Cognito uses Amazon SNS to send SMS messages. If you haven't sent an SMS message from Amazon Cognito or any other AWS service before, Amazon SNS might place your account in the SMS sandbox. We recommend that you send a test message to a verified phone number before you remove your account from the sandbox to production. Additionally, if you plan to send SMS messages to US destination phone numbers, you must obtain an origination or Sender ID from Amazon Pinpoint. To configure your Amazon Cognito user pool for SMS messages, see [SMS message settings for Amazon Cognito user pools](user-pool-sms-settings.md).
Amazon Cognito can automatically verify email addresses or phone numbers. To do this verification, Amazon Cognito sends a verification code or a verification link. For email addresses, Amazon Cognito can send a code or a link in an email message. You can choose a **Verification type** of **Code** or **Link** when you edit your **Verification message** template in the **Message templates** menu in the Amazon Cognito console. For more information, see [Customizing email verification messages](cognito-user-pool-settings-message-customizations.md#cognito-user-pool-settings-email-verification-message-customization).
For phone numbers, Amazon Cognito sends a code in an SMS text message.
Amazon Cognito must verify a phone number or email address to confirm users and help them to recover forgotten passwords. Alternatively, you can automatically confirm users with the pre sign-up Lambda trigger or use the [AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html) API operation. For more information, see [Signing up and confirming user accounts](signing-up-users-in-your-app.md).
The verification code or link is valid for 24 hours.
If you choose to require verification for an email address or phone number, Amazon Cognito automatically sends the verification code or link when a user signs up. If the user pool has a [Custom SMS sender Lambda trigger](user-pool-lambda-custom-sms-sender.md) or [Custom email sender Lambda trigger](user-pool-lambda-custom-email-sender.md) configured, that function is invoked instead.
**Notes**
Amazon SNS charges separately for SMS text messaging that it uses to verify phone numbers. There is no charge to send email messages. For information about Amazon SNS pricing, see [Worldwide SMS pricing](https://aws.amazon.com/sns/sms-pricing/). For the current list of countries where SMS messaging is available, see [Supported regions and countries](https://docs.aws.amazon.com/sns/latest/dg/sms_supported-countries.html).
When you test actions in your app that generate email messages from Amazon Cognito, use a real email address that Amazon Cognito can reach without hard bounces. For more information, see [Sending emails while testing your app](signing-up-users-in-your-app.md#managing-users-accounts-email-testing).
The forgotten password flow requires either the user's email or the user's phone number to verify the user.
**Important**
If a user signs up with both a phone number and an email address, and your user pool settings require verification of both attributes, Amazon Cognito sends a verification code to the phone number through SMS message. Amazon Cognito hasn't yet verified the email address, so your app must call [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) to see if an email address awaits verification. If it does require verification, the app must call [GetUserAttributeVerificationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html) to initiate the email verification flow. Then it must submit the verification code by calling [VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html).
You can adjust your SMS message spend quota for an AWS account and for individual messages. The limits apply only to the cost to send SMS messages. For more information, see **What are account-level and message-level spend quotas and how do they work?** in the [Amazon SNS FAQs](https://aws.amazon.com/sns/faqs/).
Amazon Cognito sends SMS messages using Amazon SNS resources in either the AWS Region where you created the user pool or in a **Legacy Amazon SNS alternate Region** from the following table. The exception is Amazon Cognito user pools in the Asia Pacific (Seoul) Region. These user pools use your Amazon SNS configuration in the Asia Pacific (Tokyo) Region. For more information, see [Choose the AWS Region for SMS messages](user-pool-sms-settings.md#sms-choose-a-region).
| Amazon Cognito Region | Legacy Amazon SNS alternate Region |
| --- | --- |
| US East (Ohio) | US East (N. Virginia) |
| Asia Pacific (Mumbai) | Asia Pacific (Singapore) |
| Asia Pacific (Seoul) | Asia Pacific (Tokyo) |
| Canada (Central) | US East (N. Virginia) |
| Europe (Frankfurt) | Europe (Ireland) |
| Europe (London) | Europe (Ireland) |
**Example: **If your Amazon Cognito user pool is in Asia Pacific (Mumbai), and you have increased your spend limit in ap-southeast-1, you might not want to request a separate increase in ap-south-1. Instead, you can use your Amazon SNS resources in Asia Pacific (Singapore).
## Verifying updates to email addresses and phone numbers
An email address or phone number attribute can become active and unverified immediately after your user changes its value. Amazon Cognito can also require that your user verifies the new value before Amazon Cognito updates the attribute. When you require that your users first verify the new value, they can use the original value for sign-in and to receive messages until they verify the new value.
When your users can use their email address or phone number as a sign-in alias in your user pool, their sign-in name for an updated attribute depends on whether you require verification of updated attributes. When you require that users verify an updated attribute, a user can sign in with the original attribute value until they verify the new value. When you don’t require that users verify an updated attribute, a user can’t sign in or receive messages at either the new or the original attribute value until they verify the new value.
For example, your user pool allows sign-in with an email address alias, and requires that users verify their email address when they update. Sue, who signs in as `sue@example.com`, wants to change her email address to `sue2@example.com` but accidentally enters `ssue2@example.com`. Sue doesn’t receive the verification email, so she can’t verify `ssue2@example.com`. Sue signs in as `sue@example.com` and resubmits the form in your app to update her email address to `sue2@example.com`. She receives this email, provides the verification code to your app, and begins signing in as `sue2@example.com`.
**When a user updates an attribute and your user pool verifies new attribute values**
+ They can sign in with the original attribute value before they have confirmed the code to verify the new value.
+ They can only sign in with the new attribute value after they have confirmed the code to verify the new value.
+ If you set `email_verified` or `phone_number_verified` to `true` in an [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API request, they can sign in before they have confirmed the code that Amazon Cognito sent to them.
**When a user updates an attribute and your user pool doesn't verify new attribute values**
+ They can’t sign in with, or receive messages at, the original attribute value.
+ They can’t sign in with, or receive messages other than a confirmation code at, the new attribute value before they have confirmed the code to verify the new value.
+ If you set `email_verified` or `phone_number_verified` to `true` in an [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API request, they can sign in before they have confirmed the code that Amazon Cognito sent to them.
## To require attribute verification when users update their email address or phone number
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. In the navigation pane, choose **User Pools**, and choose the user pool you want to edit.
1. In the **Sign-up** menu, choose **Edit** under **Attribute verification and user account confirmation**.
1. Choose **Keep original attribute value active when an update is pending**.
1. Under **Active attribute values when an update is pending**, choose the attributes that you want to require your users verify before Amazon Cognito updates the value.
1. Choose **Save changes**.
To require attribute update verification with the Amazon Cognito API, you can set the `AttributesRequireVerificationBeforeUpdate` parameter in an [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) request.
## Authorizing Amazon Cognito to send SMS messages on your behalf
To send SMS messages to your users on your behalf, Amazon Cognito needs your permission. To grant that permission, you can create an AWS Identity and Access Management (IAM) role. In the **Authentication methods** menu of the Amazon Cognito console under SMS, choose **Edit** to set a role.
# Configuring MFA, authentication, verification and invitation messages
With Amazon Cognito, you can customize SMS and email authentication, verification, and user invitation messages to enhance the security and user experience of your application. You can choose between code-based and one-click link verifications for some messages. This topic discusses how you can personalize authentication and verification communications in the Amazon Cognito console.
In the **Message templates** menu, you can customize:
+ Your email and SMS message templates for one-time password (OTP) and multi-factor (MFA) authentication
+ Your SMS and email verification messages
+ The verification type for email—code or link
**Note**
Amazon Cognito sends links with your link-based template in the verification messages when users sign up or resend a confirmation code. Emails from attribute-update and password-reset operations use the code template.
+ Your user invitation messages
+ FROM and REPLY-TO email addresses for emails going through your user pool
**Note**
The SMS and email verification message templates only appear if you have chosen to require phone number and email verification. Similarly, the SMS MFA message template only appears if the MFA setting is **required** or **optional**.
**Topics**
+ [Message templates](#cognito-user-pool-settings-message-templates)
+ [Customizing email and SMS MFA messages](#cognito-user-pool-settings-SMS-message-customization)
+ [Customizing email verification messages](#cognito-user-pool-settings-email-verification-message-customization)
+ [Customizing user invitation messages](#cognito-user-pool-settings-user-invitation-message-customization)
+ [Customizing your email address](#cognito-user-pool-settings-email-address-customization)
+ [Authorizing Amazon Cognito to send Amazon SES email on your behalf (from a custom FROM email address)](#cognito-user-pool-settings-ses-authorization-to-send-email)
## Message templates
You can use message templates to insert placeholders into your messages. Amazon Cognito replace the placeholders with the corresponding values. You can reference *Universal template placeholders* in message templates of any type, although these values won't be present in all message types.
**Universal template placeholders**
| Description | Token | Message type |
| --- | --- | --- |
| Verification code | \$1\$1\$1\$1\$1\$1 | Verification, confirmation, and MFA messages |
| Temporary password | \$1\$1\$1\$1\$1\$1 | Forgot-password and invitation messages |
| User name | \$1username\$1 | Invitation and advanced security messages |
One of the available automated responses with [threat protection](cognito-user-pool-settings-threat-protection.md) is to notify the user that Amazon Cognito detected potentially-malicious activity. You can use advanced security template placeholders to do the following:
+ Include specific details about an event such as IP address, city, country, sign-in time, and device name. Amazon Cognito threat protection can analyze these details.
+ Verify whether a one-click link is valid.
+ Use event ID, feedback token, and user name to build your own one-click link.
**Note**
To generate one-click links and use the `{one-click-link-valid}` and `{one-click-link-invalid}` placeholders in advanced security email templates, you must already have a domain configured for your user pool.
Threat protection adds the following placeholders that you can insert into the message templates. These placeholders apply to **Adaptive authentication messages**, notifications that Amazon Cognito sends to users whose sessions have been evaluated for a level of risk. To configure message templates with these variables, update the **Full-function** configuration of your threat protection in the Amazon Cognito console, or submit templates in a [SetRiskConfiguration](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetRiskConfiguration.html) request.
**Advanced security template placeholders**
| Description | Token |
| --- | --- |
| IP address | \$1ip-address\$1 |
| City | \$1city\$1 |
| Country | \$1country\$1 |
| Log-in time | \$1login-time\$1 |
| Device name | \$1device-name\$1 |
| One-click link is valid | \$1one-click-link-valid\$1 |
| One-click link is not valid | \$1one-click-link-invalid\$1 |
| Event ID | \$1event-id\$1 |
| Feedback token | \$1feedback-token\$1 |
## Customizing email and SMS MFA messages
To customize the SMS and email messages for [multi-factor authentication (MFA)](user-pool-settings-mfa.md), edit **MFA message** from the **Message templates** menu in the Amazon Cognito user pools console.
**Important**
Your custom message must contain the `{####}` placeholder. This placeholder is replaced with the authentication code before the message is sent.
Amazon Cognito sets a maximum length for SMS messages, including the authentication code, of 140 UTF-8 characters.
### Customizing SMS verification messages
To customize the SMS message for phone number verification, edit the **Verification message** template from the **Message templates** menu of your user pool.
**Important**
Your custom message must contain the `{####}` placeholder. This placeholder is replaced with the verification code before the message is sent.
The maximum length for the message, including the verification code, is 140 UTF-8 characters.
## Customizing email verification messages
To verify the email address of a user in your user pool with Amazon Cognito, you can send the user an email message with a link that they can select, or you can send them a code that they can enter.
To customize the email subject and message content for email address verification messages, edit the **Verification message** template in the **Message templates** menu of your user pool. You can choose a **Verification type** of **Code** or **Link** when you edit your **Verification message** template.
When you choose **Code** as the verification type, your custom message must contain the `{####}` placeholder. When you send the message, the verification code replaces this placeholder.
When you choose **Link** as the verification type, your custom message must include a placeholder in the format `{##Verify Your Email##}`. You can change the text string between the placeholder characters, for example `{##Click here##}`. A verification link titled *Verify Your Email* replaces this placeholder.
The link for an email verification message directs your user to a URL like the following example.
```
https:///confirmUser/?client_id=abcdefg12345678&user_name=emailtest&confirmation_code=123456
```
The maximum length for the message, including the verification code (if present), is 20,000 UTF-8 characters. You can use HTML tags in this message to format the contents.
## Customizing user invitation messages
You can customize the user invitation message that Amazon Cognito sends to new users by SMS or email message by editing the **Invitation messages** template in the **Message templates** menu.
**Important**
Your custom message must contain the `{username}` and `{####}` placeholders. When Amazon Cognito sends the invitation message, it replaces these placeholders with your user's user name and password.
The maximum length of an SMS message, including the verification code, is 140 UTF-8 characters. The maximum length of an email message, including the verification code, is 20,000 UTF-8 characters. You may use HTML tags in your email messages to format the contents.
## Customizing your email address
By default, Amazon Cognito sends email messages to users in your user pools from the address **no-reply@verificationemail.com**. You can choose to specify custom FROM and REPLY-TO email addresses instead of **no-reply@verificationemail.com**.
**To customize the FROM and REPLY-TO email addresses**
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home), and choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Authentication methods** menu. Under **Email**, choose **Edit**.
1. Choose an **SES Region**.
1. Choose a **FROM email address** from the list of email addresses you have verified with Amazon SES in the **SES Region** you selected. To use an email address from a verified domain, configure email settings in the AWS Command Line Interface or the AWS API. For more information, see [Verifying email addresses and domains in Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-addresses-and-domains.html) in the *Amazon Simple Email Service Developer Guide*.
1. Choose a **Configuration set** from the list of configuration sets in your chosen **SES Region**.
1. Enter a friendly **FROM sender name** for your email messages, in the format `John Stiles `.
1. To customize the REPLY-TO email address, enter a valid email address in the **REPLY-TO email address** field.
## Authorizing Amazon Cognito to send Amazon SES email on your behalf (from a custom FROM email address)
You can configure Amazon Cognito to send email from a custom FROM email address instead of its default address. To use a custom address, you must give Amazon Cognito permission to send email message from an Amazon SES verified identity. In most cases, you can grant permission by creating a sending authorization policy. For more information, see [Using sending authorization with Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization.html) in the *Amazon Simple Email Service Developer Guide*.
When you configure a user pool to use Amazon SES for email messages, Amazon Cognito creates the `AWSServiceRoleForAmazonCognitoIdpEmailService` role in your account to grant access to Amazon SES. No sending authorization policy is needed when the `AWSServiceRoleForAmazonCognitoIdpEmailService` service-linked role is used. You only need to add a sending authorization policy when you use both the default email functionality in your user pool *and* a verified Amazon SES identity as the FROM address.
For more information about the service-linked role that Amazon Cognito creates, see [Using service-linked roles for Amazon Cognito](using-service-linked-roles.md).
The following example sending authorization policy grants Amazon Cognito a limited ability to use an Amazon SES verified identity. Amazon Cognito can only send email messages when it does so on behalf of both the user pool in the `aws:SourceArn` condition and the account in the `aws:SourceAccount` condition. For more examples, see [Amazon SES sending authorization policy examples](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization-policy-examples.html) in the *Amazon Simple Email Service Developer Guide*.
**Note**
In this example, the "Sid" value is an arbitrary string that uniquely identifies the statement. For more information about policy syntax, see [Amazon SES sending authorization policies](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization-policies.html) in the *Amazon Simple Email Service Developer Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "stmnt1234567891234",
"Effect": "Allow",
"Principal": {
"Service": [
"email.cognito-idp.amazonaws.com"
]
},
"Action": [
"SES:SendEmail",
"SES:SendRawEmail"
],
"Resource": "arn:aws:ses:us-east-1:111122223333:identity/support@example.com",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:cognito-idp:us-east-1:111122223333:userpool/us-east-1_EXAMPLE"
}
}
}
]
}
```
------
The Amazon Cognito console adds a similar policy for you when you select an Amazon SES identity from the drop-down menu. If you use the CLI or API to configure the user pool, you must attach a policy structured like the previous example to your Amazon SES Identity.
# Creating user accounts as administrator
User pools aren't only a customer identity and access management (CIAM) user directory, where anyone on the internet can sign up for a user profile in your application. You can disable self-service sign-up. You might already know your customers and want to only admit those who have been authorized in advance. You can put manual authentication guardrails around your application with a [private SAML 2.0 or OIDC identity provider](cognito-user-pools-identity-federation.md), by [importing users](cognito-user-pools-import-users.md), by [screening users at sign-up](user-pool-lambda-pre-sign-up.md)—or by creating users with administrative API operations. Your workflow for administrative creation of users can be programmatic, provisioning users after they register in another system, or it can be on a case-by-case or testing basis in the Amazon Cognito console.
When you create users as an administrator, Amazon Cognito sets a temporary password for them and sends a welcome, or invitation, message. They can follow the link in their invitation message and sign in for the first time, setting a password and confirming their account. The page that follows describes how to create new users and configure the welcome message. For more information about user creation with the user pools API and an AWS SDK or CDK, see [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html).
After you create your user pool, you can create users using the AWS Management Console, as well as the AWS Command Line Interface or the Amazon Cognito API. You can create a profile for a new user in a user pool and send a welcome message with sign-up instructions to the user via SMS or email.
The following are some examples of how administrators can manage users in user pools.
+ Create a new user profile in the Amazon Cognito console or with the `AdminCreateUser` API operation.
+ Make username-and-password, passwordless, passkey, and custom [authentication flows](amazon-cognito-user-pools-authentication-flow-methods.md) available to your user pool and app client.
+ Set user attribute values.
+ Create custom attributes.
+ Set the value of immutable [custom attributes](user-pool-settings-attributes.md#user-pool-settings-custom-attributes) in `AdminCreateUser` API requests. This feature isn't available in the Amazon Cognito console.
+ Specify a temporary password, create a user without a password, or allow Amazon Cognito to automatically generate a password.
+ Create new users and automatically confirm their accounts, verify their email addresses, or verify their phone numbers.
+ Specify custom SMS and email invitation messages for new users via the AWS Management Console or Lambda triggers like [custom message](user-pool-lambda-custom-message.md), [custom SMS sender](user-pool-lambda-custom-sms-sender.md), and [custom email sender](user-pool-lambda-custom-email-sender.md).
+ Specify whether invitation messages are sent via SMS, email, or both.
+ Resend the welcome message to an existing user by calling the `AdminCreateUser` API, specifying `RESEND` for the `MessageAction` parameter.
+ [Suppress](#admincreateuserwalkthrough-step-invitationmessage) the sending of the invitation message when the user is created.
+ Specify an expiration time limit of up to 90 days for new user accounts.
+ Allow users to sign themselves up or require that new users only be added by the administrator.
Administrators can also sign users in with AWS credentials in a server-side application. For more information, see [Authorization models for API and SDK authentication](authentication-flows-public-server-side.md).
## User authentication flows and creating users
Administrative creation of users has options that differ based on the configuration of your user pool. The *authentication flows*, or methods available to users for sign-in and MFA, can change how you create users and the messages that you send to them. The following are some authentication flows that are available in user pools.
+ Username and password
+ Passkeys
+ Sign-in with third-party IdPs
+ Passwordless with email and SMS one-time passwords (OTPs)
+ Multi-factor authentication with email, SMS, and authenticator-app OTPs
+ Custom authentication with Lambda triggers
For more information about how to configure these sign-in factors, see [Authentication with Amazon Cognito user pools](authentication.md).
## Create users without passwords
If you have enabled passwordless sign-in for your user pool, you can create users without passwords. To create a user without a password, you must provide attribute values for an available passwordless sign-in factor. For example, if email OTP passwordless sign-in is available in your user pool, you can create a user with no password and an email address attribute. If the only authentication flows available to new users require a password, for example passkey or username-password, you must create or generate a temporary password for each new user.
**To create a new user without a password**
+ Choose **Don't set a password** in the Amazon Cognito console
+ Omit or leave blank the `TemporaryPassword` parameter of your `AdminCreateUser` API request
**Users without passwords are automatically confirmed**
Normally new users get a temporary password and go into a `FORCE_CHANGE_PASSWORD` status when you create them. When you create users without passwords, they immediately go into a `CONFIRMED` state. You can't resend confirmation codes to these users in the `CONFIRMED` state.
**Invitation messages change for users without passwords.**
By default, Amazon Cognito sends an [invitation message](cognito-user-pool-settings-message-customizations.md#cognito-user-pool-settings-user-invitation-message-customization) to new users that says `Your username is {userName} and your password is {####}.` When you create users with no password, the message says `Your username is {userName}.` Customize your invitation message to reflect whether you will set passwords for users. Omit out the `{####}` password variable in passwordless authentication models.
**You can't autogenerate passwords when passwordless factors are available**
If you have configured your user pool to support email or phone OTP passwordless sign-in, you can't automatically generate a password. For each user who will have a password, you must set a temporary password when you create their profile.
**Passwordless users must have values for all required attributes**
When you create a user *without* a password, your request only succeeds if the user provides values for all attributes that you have marked as required in your user pool. This applies to any required attribute, not only the phone number and email attributes required for OTP delivery.
## Creating users who will provide required-attribute values later
You might want to require attributes in your user pool but collect those attributes after you administratively create users, during user interaction in your application. Administrators can omit values for required attributes when they create users *with temporary passwords*. You can't omit required-attribute values for passwordless users.
Users with missing values for required attributes and a temporary password get a [NEW\$1PASSWORD\$1REQUIRED](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html#CognitoUserPools-RespondToAuthChallenge-request-ChallengeResponses) challenge at first sign-in. They can then provide a value for the missing required attributes in the `requiredAttributes` parameter. You can create users with passwords and without required attributes only if all required attributes are [mutable](user-pool-settings-attributes.md#user-pool-settings-custom-attributes). Users can only complete sign-in with `NEW_PASSWORD_REQUIRED` challenges and required-attribute values if the required attributes are [writeable](user-pool-settings-client-apps.md#cognito-user-pools-app-idp-settings-about) from the app client they sign in with.
When you set a permanent password for an administrator-created user, their status changes to `CONFIRMED` and your user pool doesn't prompt them for a new password *or* required attributes at their first sign-in.
## Creating a new user in the AWS Management Console
You can set user password requirements, configure the invitation and verification messages sent to users, and add new users with the Amazon Cognito console.
### Set a password policy and enable self-registration
You can configure settings for minimum password complexity and whether users can sign up using public APIs in your user pool.
**Configure a password policy**
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home), and choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Authentication methods** menu and locate **Password policy**. Choose **Edit**.
1. Choose a **Password policy mode** of **Custom**.
1. Choose a **Password minimum length**. For limits to the password length requirement, see [User pools resource quotas](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html#limits-hard).
1. Choose a **Password complexity** requirement.
1. Choose how long password set by administrators should be valid for.
1. Choose **Save changes**.
**Allow self-service sign-up**
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home), and choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Sign-up** menu and locate **Self-service sign-up**. Select **Edit**.
1. Choose whether to **Enable self-registration**. Self-registration is typically used with public app clients that need to register new users in your user pool without distributing a client secret or AWS Identity and Access Management (IAM) API credentials.
**Disabling self-registration**
If you do not enable self-registration, new users must be created by administrative API actions using IAM API credentials or by sign-in with federated providers.
1. Choose **Save changes**.
### Customize email and SMS messages
**Customize user messages**
You can customize the messages that Amazon Cognito sends to your users when you invite them to sign in, they sign up for a user account, or they sign in and are prompted for multi-factor authentication (MFA).
**Note**
An **Invitation message** is sent when you create a user in your user pool and invite them to sign in. Amazon Cognito sends initial sign-in information to the user's email address or phone number.
A **Verification message** is sent when a user signs up for a user account in your user pool. Amazon Cognito sends a code to the user. When the user provides the code to Amazon Cognito, they verify their contact information and confirm their account for sign-in. Verification codes are valid for 24 hours.
An **MFA message** is sent when you enable SMS MFA in your user pool, and a user that has configured SMS MFA signs in and is prompted for MFA.
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home), and choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Message templates** menu and select **Verification message**, **Invitation message**, or **MFA message** and choose **Edit**.
1. Customize the messages for the chosen message type.
**Note**
All variables in message templates must be included when you customize the message. If the variable, for example **\$1\$1\$1\$1\$1\$1**, is not included, your user will have insufficient information to complete the message action.
For more information, see [Message templates](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-message-templates.html).
1.
1. **Verification messages**
1. Choose a **Verification type** for **Email** messages. A **Code** verification sends a numeric code that the user must enter. A **Link** verification sends a link the user can click to verify their contact information. The text in the variable for a **Link** message is displayed as hyperlink text. For example, a message template using the variable \$1\$1\$1Click here\$1\$1\$1 is displayed as [Click here]() in the email message.
1. Enter an **Email subject** for **Email** messages.
1. Enter a custom **Email message** template for **Email** messages. You can customize this template with HTML.
1. Enter a custom **SMS message** template for **SMS** messages.
1. Choose **Save changes**.
1. **Invitation messages**
1. Enter an **Email subject** for **Email** messages.
1. Enter a custom **Email message** template for **Email** messages. You can customize this template with HTML.
1. Enter a custom **SMS message** template for **SMS** messages.
1. Choose **Save changes**.
1. **MFA messages**
1. Enter a custom **SMS message** template for **SMS** messages.
1. Choose **Save changes**.
### Create a user
**Create a user**
You can create new users for your user pool from the Amazon Cognito console. Typically, users can sign in after they set a password. To sign in with an email address, a user must verify the `email` attribute. To sign in with a phone number, the user must verify the `phone_number` attribute. To confirm accounts as an administrator, you can also use the AWS CLI or API, or create user profiles with a federated identity provider. For more information, see the [Amazon Cognito API Reference](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/).
1. Navigate to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home), and choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Users** menu, and choose **Create a user**.
1. Review the **User pool sign-in and security requirements** for guidance on password requirements, available account recovery methods, and alias attributes for your user pool.
1. Choose how you want to send an **Invitation message**. Choose SMS message, email message, or both. To suppress the invitation message, choose **Don't send an invitation**.
**Note**
Before you can send invitation messages, configure a sender and an AWS Region with Amazon Simple Notification Service and Amazon Simple Email Service in the **Authentication methods** menu of your user pool . Recipient message and data rates apply. Amazon SES bills you for email messages separately, and Amazon SNS bills you for SMS messages separately.
1. Choose a **Username** for the new user.
1. Choose if you want to **Create a password** or have Amazon Cognito **Generate a password** for the user. The option to generate a password isn't available if [passwordless sign-in](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless) is available in the user pool. Any temporary password must adhere to the user pool password policy.
1. Choose **Create**.
1. Choose the **Users** menu and choose the **User name** entry for the user. Add and edit **User attributes** and **Group memberships**. Review **User event history**.
# Adding groups to a user pool
Support for groups in Amazon Cognito user pools enables you to create and manage groups, add users to groups, and remove users from groups. Use groups to create collections of users to manage their permissions or to represent different types of users. You can assign an AWS Identity and Access Management (IAM) role to a group to define the permissions for members of a group.
You can use groups to create a collection of users in a user pool, which is often done to set the permissions for those users. For example, you can create separate groups for users who are readers, contributors, and editors of your website and app. Using the IAM role associated with a group, you can also set different permissions for those different groups so that only contributors can put content into Amazon S3 and only editors can publish content through an API in Amazon API Gateway.
Amazon Cognito creates a user group for each OIDC, SAMl, and social [identity provider](cognito-user-pools-identity-federation.md#cognito-user-pools-identity-federation-how-it-works) (IdP) that you add to your user pool. The name of the group is in the format `[user pool ID]_[IdP name]`, for example `us-east-1_EXAMPLE_MYSSO` or `us-east-1_EXAMPLE_Google`. Each unique automatically-generated IdP user profile is automatically added to this group. [Linked users](cognito-user-pools-identity-federation-consolidate-users.md) aren't automatically added to this group, but you can add their profiles to the group in a separate process.
You can create and manage groups in a user pool from the AWS Management Console, the APIs, and the CLI. As a developer (using AWS credentials), you can create, read, update, delete, and list the groups for a user pool. You can also add users and remove users from groups.
There is no additional cost for using groups within a user pool. See [Amazon Cognito Pricing](https://aws.amazon.com/cognito/pricing/) for more information.
## Assigning IAM roles to groups
You can use groups to control permissions to your resources using an IAM role. IAM roles include trust policies and permission policies. The role [trust](https://docs.aws.amazon.com/cognito/latest/developerguide/role-trust-and-permissions.html) policy specifies who can use the role. The [permissions](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html#access-policies) policies specify the actions and resources that your group members can access. When you create an IAM role, set up the role trust policy to allow your group's users to assume the role. In the role permissions policies, specify the permissions that you want your group to have.
When you create a group in Amazon Cognito, you specify an IAM role by providing the role’s [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns). When group members sign in using Amazon Cognito, they can receive temporary credentials from the identity pools. Their permissions are determined by the associated IAM role.
Individual users can be in multiple groups. As a developer, you have the following options for automatically choosing the IAM role when a user is in multiple groups:
+ You can assign precedence values to each group. The group with the better (lower) precedence will be chosen and its associated IAM role will be applied.
+ Your app can also choose from among the available roles when requesting AWS credentials for a user through an identity pool, by specifying a role ARN in the [GetCredentialsForIdentity](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetCredentialsForIdentity.html) `CustomRoleARN` parameter. The specified IAM role must match a role that is available to the user.
## Assigning precedence values to groups
A user can belong to more than one group. In the user's access and ID tokens, the `cognito:groups` claim contains the list of all the groups a user belongs to. The `cognito:roles` claim contains the list of roles corresponding to the groups.
Because a user can belong to more than one group, each group can be assigned a precedence. This is a non-negative number that specifies the precedence of this group relative to the other groups that a user belongs to in the user pool. Zero is the top precedence value. Groups with lower precedence values take precedence over groups with higher or null precedence values. If a user belongs to two or more groups, the group with the lowest precedence value will have its IAM role applied to the `cognito:preferred_role` claim in the user's ID token.
Two groups can have the same precedence value. If this happens, neither group takes precedence over the other. If two groups with the same precedence value have the same role ARN, that role is used in the `cognito:preferred_role` claim in ID tokens for users in each group. If the two groups have different role ARNs, the `cognito:preferred_role` claim is not set in users' ID tokens.
## Using groups to control permission with Amazon API Gateway
You can use groups in a user pool to control permission with Amazon API Gateway. The groups that a user is a member of are included in both the ID token and access token from a user pool in the `cognito:groups` claim. You can submit ID or access tokens with requests to Amazon API Gateway and use an Amazon Cognito user pool authorizer for a REST API. For more information, see [Control access to a REST API using Amazon Cognito user pools as authorizer](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html) in the [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/).
You can also authorize access to an Amazon API Gateway HTTP API with a custom JWT authorizer. For more information, see [Controlling access to HTTP APIs with JWT authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) in the [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/).
## Limitations on groups
User groups are subject to the following limitations:
+ The number of groups you can create is limited by the [Amazon Cognito service quotas](quotas.md).
+ Groups cannot be nested.
+ You cannot search for users in a group.
+ You cannot search for groups by name, but you can list groups.
## Creating a new group in the AWS Management Console
Use the following procedure to create a new group.
**To create a new group**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Groups** menu, and then choose **Create a group**.
1. On the **Create a group** page, in **Group name**, enter a friendly name for your new group.
1. You can optionally provide additional information about this group using any of the following fields:
+ **Description** - Enter details about what this new group will be used for.
+ **Precedence** - Amazon Cognito evaluates and applies all group permissions for a given user based on which groups that they belong to has a lower precedence value. The group with the lower precedence will be chosen and its associated IAM role will be applied. For more information, see [Assigning precedence values to groups](#assigning-precedence-values-to-groups).
+ **IAM role** - You can assign an IAM role to your group when you need to control permissions to your resources. If you are integrating a user pool with an identity pool, the **IAM role** setting determines which role is assigned in the user's ID token if the identity pool is configured to choose the role from the token. For more information, see [Assigning IAM roles to groups](#assigning-iam-roles-to-groups).
+ **Add users to this group** - Add existing users as members of this group after it is created.
1. Choose **Create** to confirm.
# Managing and searching for user accounts
Users pools can contains millions of users. Working with a dataset of this size is a challenge for administrators. Amazon Cognito has tools for finding and modifying user profiles. The top methods for finding users are the **Users** menu of the Amazon Cognito console, and with [ListUsers](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html). Of the methods that retrieve information about users, these are the options that don't have a cost impact unlike, for example, [AdminGetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminGetUser.html).
This section of the guide has information about finding and updating user profiles in a user pool.
## Viewing user attributes
Use the following procedure to view user attributes in the Amazon Cognito console.
**To view user attributes**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and select a user in the list.
1. On the user details page, under **User attributes**, you can view which attributes are associated with the user.
## Resetting a user's password
Use the following procedure to reset a user's password in the Amazon Cognito console.
**To reset a user's password**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and select a user in the list.
1. On the user details page, choose **Actions**, **Reset password**.
1. In the **Reset password** dialog, review the information and when ready, choose **Reset**.
This action immediately results in a confirmation code being sent to the user and disables the user’s current password by changing the user state to `RESET_REQUIRED`. The **Reset password** code is valid for 1 hour.
## Enable, disable, and delete user accounts
You can delete unused user profiles or, if you want to temporarily prevent access, disable them. Users can delete their own accounts, but only user pool administrators can enable and disable user accounts.
**Effect of deletion**
Users can't sign in with deleted user accounts and to regain access, must sign up or be created again.
**Effect of disabling accounts**
When you disable a user account, Amazon Cognito automatically invalidates all authenticated sessions, deactivates the user account for sign-in, and [revokes their access and refresh tokens](token-revocation.md). Amazon Cognito returns an `invalid_request` error with the message `User is not enabled` when a user tries to sign in to an account that you disabled. This behavior doesn't change with your [user existence disclosure settings](cognito-user-pool-managing-errors.md) for the app client. You can disable local user accounts and the local profiles of federated user accounts. When users sign in with managed login or the classic hosted UI, then you disable their account, and then they try to sign in again with the the browser cookie that maintains their authenticated session, Amazon Cognito redirects them to the login page.
**Effect of enabling accounts**
Users can immediately sign in to accounts after you enable them. User accounts are enabled by default. Users' attributes and passwords remain the same as before their account was disabled. Tokens that your application revoked, whether you disabled the user account or separately revoked the refresh token, remain non-valid after you enable the user account that owned the token.
------
#### [ Delete a user account (console) ]
**To delete a user account**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and select the radio button next to the username of a user in the list.
1. Choose **Delete**.
1. Choose **Disable user access**.
1. Choose **Delete**.
------
#### [ Delete a user account (API) ]
Users can delete their accounts with the self-service access-token-authorized [DeleteUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUser.html) API operation. The following is an example `DeleteUser` request body.
```
{
"AccessToken": "eyJra456defEXAMPLE"
}
```
Administrators can delete user accounts with the IAM-authorized [AdminDeleteUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUser.html) API operation. The following is an example `AdminDeleteUser` request body.
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
#### [ Disable a user account (console) ]
**To disable a user account**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and select the username of a user in the list.
1. On the user details page, choose **Actions**, **Disable user access**.
1. In the dialog that this creates, choose **Disable**.
------
#### [ Disable a user account (API) ]
Administrators can disable user accounts with the IAM-authorized [AdminDisableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDisableUser.html) API operation. The following is an example `AdminDisableUser` request body.
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
#### [ Enable a user account (console) ]
**To enable a user account**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). If prompted, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and select the username of a user in the list.
1. On the user details page, choose **Actions**, **Enable user access**.
1. In the dialog that this creates, choose **Enable**.
------
#### [ Enable a user account (API) ]
Administrators can enable user accounts with the IAM-authorized [AdminEnableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminEnableUser.html) API operation. The following is an example `AdminEnableUser` request body.
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
## Searching user attributes
If you have already created a user pool, you can search from the **Users** panel in the AWS Management Console. You can also use the Amazon Cognito [ListUsers API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html), which accepts a **Filter** parameter.
You can search for any of the following standard attributes. Custom attributes are not searchable.
+ username (case-sensitive)
+ email
+ phone\$1number
+ name
+ given\$1name
+ family\$1name
+ preferred\$1username
+ cognito:user\$1status (called **Status** in the Console) (case-insensitive)
+ status (called **Enabled** in the Console) (case-sensitive)
+ sub
**Note**
You can also list users with a client-side filter. The server-side filter matches no more than 1 attribute. For advanced search, use a client-side filter with the `--query` parameter of the `list-users` action in the AWS Command Line Interface. When you use a client-side filter, ListUsers returns a paginated list of zero or more users. You can receive multiple pages in a row with zero results. Repeat the query with each pagination token that is returned until you receive a null pagination token value, then review the combined result.
For more information about server-side and client-side filtering, see [Filtering AWS CLI output](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-filter.html) in the AWS Command Line Interface User Guide.
## Searching for users with the AWS Management Console
If you have already created a user pool, you can search from the **Users** panel in the AWS Management Console.
AWS Management Console searches are always prefix ("starts with") searches.
**To search for a user in the Amazon Cognito console**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). You might be prompted for your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu and enter the username in the search field. Note that some attribute values are case-sensitive (for example, **Username**).
You can also find users by adjusting the search filter to narrow the scope down to other user properties, such as **Email**, **Phone number**, or **Last name**.
## Searching for users with the `ListUsers` API
To search for users from your app, use the Amazon Cognito [ListUsers API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html). This API uses the following parameters:
+ `AttributesToGet`: An array of strings, where each string is the name of a user attribute to be returned for each user in the search results. To retrieve all attributes, don't include an `AttributesToGet` parameter or request `AttributesToGet` with a value of the literal string `null`.
+ `Filter`: A filter string of the form "`AttributeName` `Filter-Type` "`AttributeValue`"". Quotation marks within the filter string must be escaped using the backslash (`\`) character. For example, `"family_name = \"Reddy\""`. If the filter string is empty, `ListUsers` returns all users in the user pool.
+ `AttributeName`: The name of the attribute to search for. You can only search for one attribute at a time.
**Note**
You can only search for standard attributes. Custom attributes are not searchable. This is because only indexed attributes are searchable, and custom attributes cannot be indexed.
+ `Filter-Type`: For an exact match, use `=`, for example, `given_name = "Jon"`. For a prefix ("starts with") match, use `^=`, for example, `given_name ^= "Jon"`.
+ `AttributeValue`: The attribute value that must be matched for each user.
+ `Limit`: Maximum number of users to be returned.
+ `PaginationToken`: A token to get more results from a previous search. Amazon Cognito expires the pagination token after one hour.
+ `UserPoolId`: The user pool ID for the user pool on which the search should be performed.
All searches are case-insensitive. Search results are sorted by the attribute named by the `AttributeName` string, in ascending order.
## Examples of using the `ListUsers` API
The following example returns all users and includes all attributes.
```
{
"AttributesToGet": null,
"Filter": "",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
The following example returns all users whose phone numbers start with "\$11312" and includes all attributes.
```
{
"AttributesToGet": null,
"Filter": "phone_number ^= \"+1312\"",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
The following example returns the first 10 users whose family name is "Reddy". For each user, the search results include the user's given name, phone number, and email address. If there are more than 10 matching users in the user pool, the response includes a pagination token.
```
{
"AttributesToGet": [
"given_name",
"phone_number",
"email"
],
"Filter": "family_name = \"Reddy\"",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
If the previous example returns a pagination token, the following example returns the next 10 users that match the same filter string.
```
{
"AttributesToGet": [
"given_name",
"phone_number",
"email"
],
"Filter": "family_name = \"Reddy\"",
"Limit": 10,
"PaginationToken": "pagination_token_from_previous_search",
"UserPoolId": "us-east-1_samplepool"
}
```
# Passwords, account recovery, and password policies
All users who sign in to a user pool, even [federated users](cognito-terms.md#terms-federateduser), have passwords assigned to their user profiles. [Local users](cognito-terms.md#terms-localuser) and [linked users](cognito-terms.md#terms-linkeduser) must provide a password when they sign in. Federated users don't use user pool passwords, but sign in with their identity provider (IdP). You can permit users to reset their own passwords, reset or change passwords as an administrator, and [set policies](#user-pool-settings-policies) for password complexity and history.
Amazon Cognito doesn't store user passwords in plaintext. Instead, it stores a hash of each user's password with a user-specific salt. Because of this, you can't retrieve existing passwords from the user profiles in your user pools. As a best practice, don't store plaintext user passwords anywhere. Perform password resets when users forget their passwords.
## Password reset and recovery
Users forget their passwords. You might want them to be able to reset their password themselves, or you might want to require that an administrator resets their password for them. Amazon Cognito user pools have options for both models. This part of the guide covers the user pool settings and the API operations for password reset.
The [ForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html) API operation and the managed login option **Forgot your password?** send users a code that, when they confirm that they have the correct code, gives them an opportunity to set a new password with [ConfirmForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html). This is the self-service password-recovery model.
**Recovery of unverified users**
You can send recovery messages to users who have verified their email address or phone number. If they don't have a confirmed recovery email or phone, a user pool administrator can mark their email address or phone number verified. Edit the user's **User attributes** in the Amazon Cognito console and select the checkbox next to **Mark phone number as verified** or **Mark email address as verified**. You can also set `email_verified` or `phone_number_verified` to true in an [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) request. For new users, the [ResendConfirmationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html) API operation sends a new code to their email address or phone number and they can complete self-service confirmation and verification.
**Reset passwords as an administrator**
The [AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) and [AdminResetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminResetUserPassword.html) API operations are the administrator-inititated methods of password reset. `AdminSetUserPassword` sets a temporary or permanent password, and `AdminResetUserPassword` sends users a password-reset code in the same way as `ForgotPassword`.
### Configure password reset and recovery
Amazon Cognito automatically selects your account-recovery options from the required attributes and sign-in options that you choose when you create a user pool in the console. You can modify these default settings.
A user's preferred MFA method influences the methods they can use to recover their password. Users whose preferred MFA is by email message can't receive a password-reset code by email. Users whose preferred MFA is by SMS message can't receive a password-reset code by SMS.
Your [password recovery](#user-pool-password-reset-and-recovery) settings must provide an alternative option when users aren't eligible for your preferred password-reset method. For example, your recovery mechanisms might have email as first priority and email MFA might be an option in your user pool. In this case, add SMS-message account recovery as a second option or use administrative API operations to reset passwords for those users.
Amazon Cognito replies to password-reset requests from users who don't have a valid recovery method with an `InvalidParameterException` error response.
**Note**
Users can't receive MFA and password reset codes at the same email address or phone number. If they use one-time passwords (OTPs) from email messages for MFA, they must use SMS messages for account recovery. If they use OTPs from SMS messages for MFA, they must use email messages for account recovery. In user pools with MFA, users might be unable to complete self-service password recovery if they have attributes for their email address but no phone number, or their phone number but no email address.
To prevent the state where users can't reset their passwords in user pools with this configuration, set the `email` and `phone_number` [attributes as required](user-pool-settings-attributes.md). As an alternative, you can set up processes that always collect and set those attributes when users sign up or when your administrators create user profiles. When users have both attributes, Amazon Cognito automatically sends password-reset codes to the destination that is *not* the user's MFA factor.
The following procedure configures self-service account recovery in a user pool.
------
#### [ Configure self-service password reset (API/SDK) ]
The `AccountRecoverySetting` parameter is the user pool parameter that sets the methods that users can use to recover their password in [ForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html) API requests or when they select **Forgot password?** in managed login. `ForgotPassword` sends a recovery code to a verified email or a verified phone number. The recovery code is valid for one hour. When you specify an [AccountRecoverySetting](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AccountRecoverySettingType.html) for your user pool, Amazon Cognito chooses the code delivery destination based on the priority that you set.
When you define `AccountRecoverySetting` and a user has SMS MFA configured, SMS cannot be used as an account recovery mechanism. The priority for this setting is determined with `1` being of the highest priority. Amazon Cognito sends a verification to only one of the specified methods. The following example `AccountRecoverySetting` sets email addresses as the primary destination for account-recovery codes, falling back to SMS message if the user doesn't have an email address attribute.
```
"AccountRecoverySetting": {
"RecoveryMechanisms": [
{
"Name": "verified_email",
"Priority": 1
},
{
"Name": "verified_phone_number",
"Priority": 2
}
]
}
```
The value `admin_only` turns off self-service account recovery, instead requiring users to contact their administrator for password reset. You cannot use `admin_only` with any other account recovery mechanism. The following e
```
"AccountRecoverySetting": {
"RecoveryMechanisms": [
{
"Name": "admin_only",
"Priority": 1
}
]
}
```
If you do not specify `AccountRecoverySetting`, Amazon Cognito sends the recovery code to a verified phone number first, and to a verified email address if users don't have a phone number attribute.
For more information about `AccountRecoverySetting`, see [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) and [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html).
------
#### [ Configure self-service password reset (console) ]
Configure account-recovery and password-reset options from the **Sign-in** menu of your user pool.
**To set up user account recovery**
1. Sign in to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home).
1. Choose **User Pools**.
1. Choose an existing user pool from the list, or [create a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html).
1. Choose the **Sign-in** menu. Locate **User account recovery** and choose **Edit**
1. To permit users to reset their own passwords, choose **Enable self-service account recovery**.
1. Configure the delivery method for the password-recovery codes that your user pool sends to users. Under **Delivery method for user account recovery messages**, select an available option. As a best practice, choose an option that has a secondary method for sending messages, for example **Email if available, otherwise SMS**. With a secondary delivery method, Amazon Cognito can send codes to users in a way that requires them to use a different medium for password reset than for MFA.
1. Select **Save changes**.
------
### Forgot password behavior
In a given hour, we allow between 5 and 20 attempts for a user to request or enter a password reset code as part of forgot-password and confirm-forgot-password actions. The exact value depends on the risk parameters associated with the requests. Please note that this behavior is subject to change.
## Adding user pool password requirements
Strong, complex passwords are a security best practice for your user pool. Especially in applications that are open to the internet, weak passwords can expose your users' credentials to systems that guess passwords and try to access your data. The more complex a password is, the more difficult it is to guess. Amazon Cognito has additional tools for security-conscious administrators, like [threat protection](cognito-user-pool-settings-threat-protection.md#cognito-user-pool-settings-threat-protection.title) and [AWS WAF web ACLs](user-pool-waf.md#user-pool-waf.title), but your password policy is a central element of the security of your user directory.
Passwords for local users in Amazon Cognito user pools don't automatically expire. As a best practice, log the time, date, and metadata of user password resets in an external system. With an external log of password age, your application or a Lambda trigger can look up a user's password age and require a reset after a given period.
You can configure your user pool to require a minimum password complexity that conforms to your security standards. Complex passwords have a minimum length of at least eight characters. They also include a mix of uppercase, numeric, and special characters.
With the Essentials or Plus feature tiers, you can also set a policy for password reuse. You can prevent a user from resetting their password to a new password that matches their current password or any of up to 23 additional previous passwords, for a maximum total of 24.
**To set a user pool password policy**
1. Create a user pool and navigate to the **Configure security requirements** step, or access an existing user pool and navigate to the **Authentication methods** menu.
1. Navigate to **Password policy**.
1. Choose a **Password policy mode**. **Cognito defaults** configures your user pool with the recommended minimum settings. You can also choose a **Custom** password policy.
1. Set a **Password minimum length**. All users must sign up or be created with a password whose length is greater than or equal to this value. You can set this minimum value as high as 99, but your users can set passwords up to 256 characters long.
1. Configure password complexity rules under **Password requirements**. Choose the character types–numbers, special characters, uppercase letters, and lowercase letters–that you want to require at least one of in each user's password.
You can require at least one of the following characters in passwords. After Amazon Cognito verifies that passwords contain the minimum required characters, your users' passwords can contain additional characters of any type up to the maximum password length.
+ Uppercase and lowercase [basic latin](https://en.wikipedia.org/wiki/ISO_basic_Latin_alphabet) letters
+ Numbers
+ The following special characters.
```
^ $ * . [ ] { } ( ) ? " ! @ # % & / \ , > < ' : ; | _ ~ ` = + -
```
+ Non-leading, non-trailing space characters.
1. Set a value for **Temporary passwords set by administrators expire in**. After this period has passed, a new user that you created in the Amazon Cognito console or with `AdminCreateUser` can't sign in and set a new password. After they sign in with their temporary password, their user accounts never expire. To update the password duration in the Amazon Cognito user pools API, set a value for [TemporaryPasswordValidityDays ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_PasswordPolicyType.html#CognitoUserPools-Type-PasswordPolicyType-TemporaryPasswordValidityDays) in your [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) or [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API request.
1. Set a value for **Prevent use of previous passwords**, if available. To use this feature, choose the Essentials or Plus [feature tier](cognito-sign-in-feature-plans.md) in your user pool. The value of this parameter is the number of previous passwords that a new password is prevented from matching when a user resets their password.
To reset access for an expired user account, do one of the following:
+ Send a new temporary password and reset the expiration period with an [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API request that has `MessageAction` set to `RESEND`.
+ Delete the user profile and create a new one.
+ Generate a new confirmation code in an [AdminResetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminResetUserPassword.html) API request.
# Importing users into a user pool
There are two ways you can import or migrate users from your existing user directory or user database into Amazon Cognito user pools. You can migrate users when they sign-in using Amazon Cognito for the first time with a user migration Lambda trigger. With this approach, users can continue using their existing passwords and will not have to reset them after the migration to your user pool. Alternatively, you can migrate users in bulk by uploading a CSV file containing the user profile attributes for all users. The following sections describe both these approaches.
**More resources**
+ [Approaches for migrating users to Amazon Cognito user pools](https://aws.amazon.com/blogs/security/approaches-for-migrating-users-to-amazon-cognito-user-pools/)
+ [AWS re:Inforce 2023 - Migrating to Amazon Cognito](https://www.youtube.com/watch?v=OkDj9uXWwCc)
**Topics**
+ [Importing users with a user migration Lambda trigger](cognito-user-pools-import-using-lambda.md)
+ [Importing users into user pools from a CSV file](cognito-user-pools-using-import-tool.md)
# Importing users with a user migration Lambda trigger
With this approach, you can seamlessly migrate users from your existing user directory to user pools when a user signs in for the first time with your app or requests a password reset. Add a [Migrate user Lambda trigger](user-pool-lambda-migrate-user.md) function to your user pool and it receives metadata about users who try to sign in, and returns user profile information from an external identity source. For details and example code for this Lambda trigger, including request and response parameters, see [Migrate user Lambda trigger parameters](user-pool-lambda-migrate-user.md#cognito-user-pools-lambda-trigger-syntax-user-migration).
Before you start to migrate users, create a user migration Lambda function in your AWS account, and set the Lambda function as the user migration trigger in your user pool. Add an authorization policy to your Lambda function that permits only the Amazon Cognito service account principal, `cognito-idp.amazonaws.com` to invoke the Lambda function, and only in the context of your own user pool. For more information, see [Using resource-based policies for AWS Lambda (Lambda function policies)](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html).
**Sign-in process**
1. The user opens your app and signs in with the Amazon Cognito user pools API or through managed login. For more information about how to facilitate sign-in with Amazon Cognito APIs, see [Integrating Amazon Cognito authentication and authorization with web and mobile apps](cognito-integrate-apps.md).
1. Your app sends the user name and password to Amazon Cognito. If your app has a custom sign-in UI that you built with an AWS SDK, your app must use [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) or [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) with the `USER_PASSWORD_AUTH` or `ADMIN_USER_PASSWORD_AUTH` flow. When your app uses one of these flows, the SDK sends the password to the server.
**Note**
Before you add a user migration trigger, activate the `USER_PASSWORD_AUTH` or `ADMIN_USER_PASSWORD_AUTH` flow in the settings of your app client. You must use these flows instead of the default `USER_SRP_AUTH` flow. Amazon Cognito must send a password to your Lambda function so that it can verify your user's authentication in the other directory. An SRP obscures your user's password from your Lambda function.
1. Amazon Cognito checks if the submitted user name matches a user name or alias in the user pool. You can set the user's email address, phone number, or preferred user name as an alias in your user pool. If the user doesn't exist, Amazon Cognito sends parameters, including the user name and password, to your [Migrate user Lambda trigger](user-pool-lambda-migrate-user.md) function.
1. Your [Migrate user Lambda trigger](user-pool-lambda-migrate-user.md) function checks for or authenticates the user with your existing user directory or user database. The function returns user attributes that Amazon Cognito stores in the user's profile in the user pool. You can return a `username` parameter only if the submitted user name matches an alias attribute. If you want users to continue to use their existing passwords, your function sets the attribute `finalUserStatus` to `CONFIRMED` in the Lambda response. Your app must return all `"response"` parameters shown at [Migrate user Lambda trigger parameters](user-pool-lambda-migrate-user.md#cognito-user-pools-lambda-trigger-syntax-user-migration).
**Important**
Do not log the entire request event object in your user migration Lambda code. This request event object includes the user's password. If you don't sanitize the logs, passwords appear in CloudWatch Logs.
1. Amazon Cognito creates the user profile in your user pool, and returns tokens to your app client.
1. Your app performs token intake, accepts the user authentication, and proceeds to the requested content.
After you migrate your users, use `USER_SRP_AUTH` for sign-in. The Secure Remote Password (SRP) protocol doesn't send the password across the network, and provides security benefits over the `USER_PASSWORD_AUTH` flow that you use during migration.
In case of errors during migration, including client device or network issues, your app receives error responses from the Amazon Cognito user pools API. When this happens, Amazon Cognito might or might not create the user account in your user pool. The user should then attempt to sign in again. If sign-in fails repeatedly, attempt to reset the user's password with the forgot-password flow in your app.
The forgot-password flow also invokes your [Migrate user Lambda trigger](user-pool-lambda-migrate-user.md) function with a `UserMigration_ForgotPassword` event source. Because the user doesn't submit a password when they request a password reset, Amazon Cognito doesn't include a password in the event that it sends to your Lambda function. Your function can only look up the user in your existing user directory and return attributes to add to the user profile in your user pool. After your function completes its invocation and returns its response to Amazon Cognito, your user pool sends a password reset code by email or SMS. In your app, prompt your user for their confirmation code and a new password, then send that information to Amazon Cognito in a [ConfirmForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html) API request. You can also use the built-in pages for the forgot-password flow in managed login.
**Additional resources**
+ [Approaches for migrating users to Amazon Cognito user pools](https://aws.amazon.com/blogs/security/approaches-for-migrating-users-to-amazon-cognito-user-pools/)
# Importing users into user pools from a CSV file
When you have an external identity store and the time to prepare your user pool for new local users, a bulk user import from a comma-separated values (CSV) file can be a low-effort, low-cost option for a migration to an Amazon Cognito user pool. A CSV file import is a process of downloading and populating a template file, then handing off the file to your user pool in an import job. You can use a CSV import to quickly create test users. You can also programmatically populate the file with read API requests to your external identity store, followed by parsing their details and attributes into write operations to the file.
The import process sets values for all user attributes except **password**. Password import is not supported, because security best practices require that passwords are not available as plain text, and we don't support importing hashes. This means that your users must change their passwords the first time they sign in. Your users are in a `RESET_REQUIRED` state when imported using this method.
The lowest-effort way to import users from a CSV is to activate [passwordless sign-in](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless) in your user pool. With email address and phone number attributes and the right user pool configuration, users can sign in with email or SMS one-time passwords (OTPs) immediately after your import job completes. For more information, see [Requiring imported users to reset their passwords](#cognito-user-pools-using-import-tool-password-reset).
You can also set your users' passwords with an [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API request that sets the `Permanent` parameter to `true`. CSV import doesn't contribute to the billed monthly active users (MAUs) in your user pool. However, password-reset operations do generate MAUs. To manage costs when you import large numbers of users with password who might not be immediately active, set up your application to prompt users for a new password when they sign in and receive the `RESET_REQUIRED` challenge.
**Note**
The creation date for each user is the time when that user was imported into the user pool. Creation date is not one of the imported attributes.
**Steps to create a user import job**
1. Create an Amazon CloudWatch Logs role in the AWS Identity and Access Management (IAM) console.
1. Create the user import .csv file.
1. Create and run the user import job.
1. Upload the user import .csv file.
1. Start and run the user import job.
1. Use CloudWatch to check the event log.
1. Require the imported users to reset their passwords.
**More resources**
+ [Cognito User Profiles Export Reference Architecture](https://aws.amazon.com/solutions/implementations/cognito-user-profiles-export-reference-architecture/) for exporting user accounts between user pools
**Topics**
+ [Creating the CloudWatch Logs IAM role](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role)
+ [Creating the user import CSV file](#cognito-user-pools-using-import-tool-csv-header)
+ [Creating and running the Amazon Cognito user pool import job](#cognito-user-pools-creating-import-job)
+ [Viewing the user pool import results in the CloudWatch console](#cognito-user-pools-using-import-tool-cloudwatch)
+ [Requiring imported users to reset their passwords](#cognito-user-pools-using-import-tool-password-reset)
## Creating the CloudWatch Logs IAM role
If you're using the Amazon Cognito CLI or API, then you need to create a CloudWatch IAM role. The following procedure describes how to create an IAM role that Amazon Cognito can use to write the results of your import job to CloudWatch Logs.
**Note**
When you create an import job in the Amazon Cognito console, you can create the IAM role at the same time. When you choose to **Create a new IAM role**, Amazon Cognito automatically applies the appropriate trust policy and IAM policy to the role.
**To create the CloudWatch Logs IAM role for user pool import (AWS CLI, API)**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Create a new IAM role for an AWS service. For detailed instructions, see [Creating a role for an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) in the *AWS Identity and Access Management User Guide*.
1. When you select a **Use case** for your **Trusted entity type**, choose any service. Amazon Cognito isn't currently listed in service use cases.
1. In the **Add permissions** screen, choose **Create policy** and insert the following policy statement. Replace *REGION* with the AWS Region of your user pool, for example `us-east-1`. Replace *ACCOUNT* with your AWS account ID, for example `111122223333`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/cognito/*"
]
}
]
}
```
------
1. Because you didn't choose Amazon Cognito as the trusted entity when you created the role, you now must manually edit the trust relationship of the role. Choose **Roles** from navigation pane of the IAM console, then choose the new role that you created.
1. Choose the **Trust relationships** tab.
1. Choose **Edit trust policy**.
1. Paste the following policy statement into **Edit trust policy**, replacing any existing text:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cognito-idp.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Choose **Update policy**.
1. Note the role ARN. You'll provide the ARN when you create your import job.
## Creating the user import CSV file
Before you can import your existing users into your user pool, you must create a comma-separated values (CSV) file that contains the users that you want to import, and their attributes. From your user pool, you can retrieve a user import file with headers that reflect the attribute schema of your user pool. You can then insert user information that matches the formatting requirements in [Formatting the CSV file](#cognito-user-pools-using-import-tool-formatting-csv-file).
### Downloading the CSV file header (console)
Use the following procedure to download the CSV header file.
**To download the CSV file header**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). You might be prompted for your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu.
1. In the **Import users** section, choose **Create an import job**.
1. Under **Upload CSV**, select the *template.csv* link and download the CSV file.
### Downloading the CSV file header (AWS CLI)
To get a list of the correct headers, from the **Users menu** under **Import users**, select **Create import job**. In the dialog that follows, select the `template.csv` link to download a template file with your user pool attributes.
You can also run the following CLI command, where *USER\$1POOL\$1ID* is the user pool identifier for the user pool you'll import users into:
```
aws cognito-idp get-csv-header --user-pool-id "USER_POOL_ID"
```
Sample response:
```
{
"CSVHeader": [
"name",
"given_name",
"family_name",
"middle_name",
"nickname",
"preferred_username",
"profile",
"picture",
"website",
"email",
"email_verified",
"gender",
"birthdate",
"zoneinfo",
"locale",
"phone_number",
"phone_number_verified",
"address",
"updated_at",
"cognito:mfa_enabled",
"cognito:username"
],
"UserPoolId": "USER_POOL_ID"
}
```
### Formatting the CSV file
The downloaded user import CSV header file looks like the following string. It also includes any custom attributes you have added to your user pool.
```
cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
```
Edit your CSV file so that it includes this header and the attribute values for your users, and is formatted according to the following rules:
**Note**
For more information about attribute values, such as proper format for phone numbers, see [Working with user attributes](user-pool-settings-attributes.md).
+ The first row in the file is the downloaded header row, which contains the user attribute names.
+ The order of columns in the CSV file doesn't matter.
+ Each row after the first row contains the attribute values for a user.
+ All columns in the header must be present, but you don't need to provide values in every column.
+ The following attributes are required:
+ **cognito:username**
+ **email\$1verified** or **phone\$1number\$1verified**
+ At least one of the auto-verified attributes must be `true` for each user. An auto-verified attribute is an email address or phone number that Amazon Cognito automatically sends a code to when a new user joins your user pool.
+ The user pool must have at least one auto-verified attribute, either **email\$1verified** or **phone\$1number\$1verified**. If the user pool has no auto-verified attributes, the import job will not start.
+ If the user pool only has one auto-verified attribute, that attribute must be verified for each user. For example, if the user pool has only **phone\$1number** as an auto-verified attribute, the **phone\$1number\$1verified** value must be `true` for each user.
**Note**
For users to reset their passwords, they must have a verified email or phone number. Amazon Cognito sends a message containing a reset password code to the email or phone number specified in the CSV file. If the message is sent to the phone number, it is sent by SMS message. For more information, see [Verifying contact information at sign-up](signing-up-users-in-your-app.md#allowing-users-to-sign-up-and-confirm-themselves).
+ **email** (if **email\$1verified** is `true`)
+ **phone\$1number** (if **phone\$1number\$1verified** is `true`)
+ Any attributes that you marked as required when you created the user pool
+ Attribute values that are strings should *not* be in quotation marks.
+ If an attribute value contains a comma, you must put a backslash (\$1) before the comma. This is because the fields in a CSV file are separated by commas.
+ The CSV file contents should be in UTF-8 format without byte order mark.
+ The **cognito:username** field is required and must be unique within your user pool. It can be any Unicode string. However, it cannot contain spaces or tabs.
+ The **birthdate** values, if present, must be in the format **mm/dd/yyyy**. This means, for example, that a birthdate of February 1, 1985 must be encoded as **02/01/1985**.
+ The **cognito:mfa\$1enabled** field must correspond to the MFA requirements of your user pool. If you've set multi-factor authentication (MFA) to be required in your user pool, this field must be `true` or blank for all users. If you've set MFA to be off, this field must be `false` or blank for all users. A blank value sets imported users' MFA-enabled status to the state required by the user pool. You can import users in an MFA-required user pool without a valid MFA factor, regardless of whether you set a `cognito:mfa_enabled` value. Users in this state have MFA active but can't sign in until they configure an email attribute, phone number attribute, or a TOTP, and that configuration is a valid MFA factor in your user pool.
+ The maximum row length is 16,000 characters.
+ The maximum CSV file size is 100 MB.
+ The maximum number of rows (users) in the file is 500,000. This maximum doesn't include the header row.
+ The **updated\$1at** field value is expected to be epoch time in seconds, for example: **1471453471**.
+ Any leading or trailing white space in an attribute value will be trimmed.
The following list is a example CSV import file for a user pool with no custom attributes. Your user pool schema might differ from this example. In that case, you must provide test values in the CSV template that you download from your user pool.
```
cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
John,,John,Doe,,,,,,,johndoe@example.com,TRUE,,02/01/1985,,,+12345550100,TRUE,123 Any Street,,FALSE
Jane,,Jane,Roe,,,,,,,janeroe@example.com,TRUE,,01/01/1985,,,+12345550199,TRUE,100 Main Street,,FALSE
```
## Creating and running the Amazon Cognito user pool import job
This section describes how to create and run the user pool import job by using the Amazon Cognito console and the AWS Command Line Interface (AWS CLI).
**Topics**
+ [Importing users from a CSV file (console)](#cognito-user-pools-using-import-tool-console)
+ [Importing users (AWS CLI)](#cognito-user-pools-using-import-tool-cli)
### Importing users from a CSV file (console)
The following procedure describes how to import the users from the CSV file.
**To import users from the CSV file (console)**
1. Go to the [Amazon Cognito console](https://console.aws.amazon.com/cognito/home). You might be prompted for your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Users** menu.
1. In the **Import users** section, choose **Create an import job**.
1. On the **Create import job** page, enter a **Job name**.
1. Choose to **Create a new IAM role** or to **Use an existing IAM role**.
1. If you chose **Create a new IAM role**, enter a name for your new role. Amazon Cognito will automatically create a role with the correct permissions and trust relationship. The IAM principal that creates the import job must have permissions to create IAM roles.
1. If you chose **Use an existing IAM role**, choose a role from the list under **IAM role selection**. This role must have the permissions and trust policy described in [Creating the CloudWatch Logs IAM role](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role).
1. Under **Upload CSV**, choose **Choose file** and attach the CSV file that you prepared.
1. Choose **Create job** to submit your job, but start it later. Choose **Create and start job** to submit your job and start it immediately.
1. If you created your job but didn't start it, you can start it later. In the **Users** menu under **Import users**, choose your import job, then select **Start**. You can also submit a [StartUserImportJob](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_StartUserImportJob.html) API request from an AWS SDK.
1. Monitor the progress of your user import job in the **Users** menu under **Import users**. If your job doesn't succeed, you can select the **Status** value. For additional details, select **View the CloudWatch logs for more details** and review any issues in the CloudWatch Logs console.
### Importing users (AWS CLI)
The following CLI commands are available for importing users into a user pool:
+ `create-user-import-job`
+ `get-csv-header`
+ `describe-user-import-job`
+ `list-user-import-jobs`
+ `start-user-import-job`
+ `stop-user-import-job`
To get the list of command line options for these commands, use the `help` command line option. For example:
```
aws cognito-idp get-csv-header help
```
#### Creating a user import job
After you create your CSV file, create a user import job by running the following CLI command, where *JOB\$1NAME* is the name you're choosing for the job, *USER\$1POOL\$1ID* is the user pool ID for the user pool into which the new users will be added, and *ROLE\$1ARN* is the role ARN you received in [Creating the CloudWatch Logs IAM role](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role):
```
aws cognito-idp create-user-import-job --job-name "JOB_NAME" --user-pool-id "USER_POOL_ID" --cloud-watch-logs-role-arn "ROLE_ARN"
```
The *PRE\$1SIGNED\$1URL* returned in the response is valid for 15 minutes. After that time, it will expire and you must create a new user import job to get a new URL.
**Example response:**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"JobName": "JOB_NAME",
"JobId": "JOB_ID",
"PreSignedUrl": "PRE_SIGNED_URL",
"CloudWatchLogsRoleArn": "ROLE_ARN",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
#### Status values for a user import job
In the responses to your user import commands, you'll see one of the following `Status` values:
+ `Created` - The job was created but not started.
+ `Pending` - A transition state. You have started the job, but it has not begun importing users yet.
+ `InProgress` - The job has started, and users are being imported.
+ `Stopping` - You have stopped the job, but the job has not stopped importing users yet.
+ `Stopped` - You have stopped the job, and the job has stopped importing users.
+ `Succeeded` - The job has completed successfully.
+ `Failed` - The job has stopped due to an error.
+ `Expired` - You created a job, but did not start the job within 24-48 hours. All data associated with the job was deleted, and the job can't be started.
#### Uploading the CSV file
Use the following `curl` command to upload the CSV file containing your user data to the presigned URL that you obtained from the response of the `create-user-import-job` command.
```
curl -v -T "PATH_TO_CSV_FILE" -H "x-amz-server-side-encryption:aws:kms" "PRE_SIGNED_URL"
```
In the output of this command, look for the phrase `"We are completely uploaded and fine"`. This phrase indicates that the file was uploaded successfully. Your user pools don't keep the information in your import files after you run your import jobs. After they complete or expire, Amazon Cognito deletes your uploaded CSV file.
#### Describing a user import job
To get a description of your user import job, use the following command, where *USER\$1POOL\$1ID* is your user pool ID, and *JOB\$1ID* is the job ID that was returned when you created the user import job.
```
aws cognito-idp describe-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"
```
**Example Sample response:**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"JobName": "JOB_NAME",
"JobId": "JOB_ID",
"PreSignedUrl": "PRE_SIGNED_URL",
"CloudWatchLogsRoleArn":"ROLE_ARN",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
In the preceding sample output, the *PRE\$1SIGNED\$1URL* is the URL that you uploaded the CSV file to. The *ROLE\$1ARN* is the CloudWatch Logs role ARN that you received when you created the role.
#### Listing your user import jobs
To list your user import jobs, use the following command:
```
aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 2
```
**Example Sample response:**
```
{
"UserImportJobs": [
{
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"JobName": "JOB_NAME",
"JobId": "JOB_ID",
"PreSignedUrl":"PRE_SIGNED_URL",
"CloudWatchLogsRoleArn":"ROLE_ARN",
"FailedUsers": 0,
"CreationDate": 1470957431.965
},
{
"CompletionDate": 1470954227.701,
"StartDate": 1470954226.086,
"Status": "Failed",
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "JOB_NAME",
"CompletionMessage": "Too many users have failed or been skipped during the import.",
"JobId": "JOB_ID",
"PreSignedUrl":"PRE_SIGNED_URL",
"CloudWatchLogsRoleArn":"ROLE_ARN",
"FailedUsers": 5,
"CreationDate": 1470953929.313
}
],
"PaginationToken": "PAGINATION_TOKEN"
}
```
Jobs are listed in chronological order from last created to first created. The *PAGINATION\$1TOKEN* string after the second job indicates that there are additional results for this list command. To list the additional results, use the `--pagination-token` option as follows:
```
aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 10 --pagination-token "PAGINATION_TOKEN"
```
#### Starting a user import job
To start a user import job, use the following command:
```
aws cognito-idp start-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"
```
Only one import job can be active at a time per account.
**Example Sample response:**
```
{
"UserImportJob": {
"Status": "Pending",
"StartDate": 1470957851.483,
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "JOB_NAME",
"JobId": "JOB_ID",
"PreSignedUrl":"PRE_SIGNED_URL",
"CloudWatchLogsRoleArn": "ROLE_ARN",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
#### Stopping a user import job
To stop a user import job while it is in progress, use the following command. After you stop the job, it cannot be restarted.
```
aws cognito-idp stop-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"
```
**Example Sample response:**
```
{
"UserImportJob": {
"CompletionDate": 1470958050.571,
"StartDate": 1470958047.797,
"Status": "Stopped",
"UserPoolId": "USER_POOL_ID",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "JOB_NAME",
"CompletionMessage": "The Import Job was stopped by the developer.",
"JobId": "JOB_ID",
"PreSignedUrl":"PRE_SIGNED_URL",
"CloudWatchLogsRoleArn": "ROLE_ARN",
"FailedUsers": 0,
"CreationDate": 1470957972.387
}
}
```
## Viewing the user pool import results in the CloudWatch console
You can view the results of your import job in the Amazon CloudWatch console.
**Topics**
+ [Viewing the results](#cognito-user-pools-using-import-tool-viewing-the-results)
+ [Interpreting the results](#cognito-user-pools-using-import-tool-interpreting-the-results)
### Viewing the results
The following steps describe how to view the user pool import results.
**To view the results of the user pool import**
1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choose **Logs**.
1. Choose the log group for your user pool import jobs. The log group name is in the form `/aws/cognito/userpools/USER_POOL_ID/USER_POOL_NAME`.
1. Choose the log for the user import job you just ran. The log name is in the form *JOB\$1ID*/*JOB\$1NAME*. The results in the log refer to your users by line number. No user data is written to the log. For each user, a line similar to the following appears:
+ `[SUCCEEDED] Line Number 5956 - The import succeeded.`
+ `[SKIPPED] Line Number 5956 - The user already exists.`
+ `[FAILED] Line Number 5956 - The User Record does not set any of the auto verified attributes to true. (Example: email_verified to true).`
### Interpreting the results
Successfully imported users have their status set to "PasswordReset".
In the following cases, the user will not be imported, but the import job will continue:
+ No auto-verified attributes are set to `true`.
+ The user data doesn't match the schema.
+ The user couldn't be imported due to an internal error.
In the following cases, the import job will fail:
+ The Amazon CloudWatch Logs role cannot be assumed, doesn't have the correct access policy, or has been deleted.
+ The user pool has been deleted.
+ Amazon Cognito is unable to parse the .csv file.
## Requiring imported users to reset their passwords
If your user pool only offers password-based sign-in, users must reset their passwords after they are imported. The first time they sign in, they can enter *any* password. Amazon Cognito prompts them to enter a new password in the API response to the sign-in request from your application.
If your user pool has passwordless authentication factors, Amazon Cognito defaults to those for imported users. They're not prompted for a new password, and can sign in immediately with a passwordless email or SMS OTP. You can also prompt users to set a password so that they can complete other sign-in methods like username-password and passkey. The following conditions apply to passwordless sign-in after user import.
1. You must import users with an attribute that corresponds to an available passwordless sign-in factor. If users can sign in with an email address, you must import an `email` attribute. If a phone number, you must import a `phone_number` attribute. If both, import a value for either attribute.
1. Normally, users import in a `RESET_REQUIRED` state where they must reset their password. If they are imported with the ability to sign in with a passwordless factor, Amazon Cognito sets their state to `CONFIRMED`.
For more information about passwordless authentication including how to set it up and how to construct the authentication flow in your application, see [Authentication with Amazon Cognito user pools](authentication.md).
The following procedure describes the user experience in a custom-built login mechanism with local users in a `RESET_REQUIRED` after you import a CSV file. If your users sign in with managed login, instruct them to select the **Forgot password?** option, provide the code from their email or text message, and set a password.
**Requiring imported users to reset their passwords**
1. In your app, silently attempt sign-in for the current user with `InitiateAuth` using a random password.
1. Amazon Cognito returns a `NotAuthorizedException` when `PreventUserExistenceErrors` is enabled. Otherwise, it returns `PasswordResetRequiredException`.
1. Your app makes a `ForgotPassword` API request and resets the user's password.
1. The app submits the username in a `ForgotPassword` API request.
1. Amazon Cognito sends a code to the verified email or phone number. The destination depends on the values you provided for `email_verified` and `phone_number_verified` in your CSV file. The response to the `ForgotPassword` request indicates the destination of the code.
**Note**
Your user pool must be configured to verify emails or phone numbers. For more information, see [Signing up and confirming user accounts](signing-up-users-in-your-app.md).
1. Your app displays a message to your user to check the location where the code was sent, and prompts your user to enter the code and a new password.
1. The user enters the code and new password in the app.
1. The app submits the code and new password in a `ConfirmForgotPassword` API request.
1. Your app redirects your user to sign-in.
# 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](user-pool-lambda-pre-sign-up.md).
**Note**
Some documentation and standards refer to attributes as *members*.
**Topics**
+ [Standard attributes](#cognito-user-pools-standard-attributes)
+ [Username and preferred username](#user-pool-settings-usernames)
+ [Customizing sign-in attributes](#user-pool-settings-aliases)
+ [Custom attributes](#user-pool-settings-custom-attributes)
+ [Attribute permissions and scopes](#user-pool-settings-attribute-permissions-and-scopes)
## Standard attributes
Amazon Cognito assigns all users a set of standard attributes based on the [OpenID Connect specification](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). 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\$1number** attributes can be verified.
Standard attributes have predefined properties that you can view in the `SchemaAttributes` parameter of a [DescribeUserPool API response](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPool.html#API_DescribeUserPool_ResponseSyntax). 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Schema). 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html) 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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API or the [admin-update-user-attributes](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-update-user-attributes.html) 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](https://datatracker.ietf.org/doc/html/rfc3696#section-3) following the standard email format with @ symbol and domain, up to 2048 characters in length.
**phone\$1number**
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](user-pool-settings-mfa.md).
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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html) API or the [admin-update-user-attributes](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-update-user-attributes.html) 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.
Phone numbers must follow these format rules: A phone number must start with a plus (**\$1**) sign, followed immediately by the country code. A phone number can only contain the **\$1** 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: **\$114325551212**.
**preferred\$1username**
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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html) 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](how-to-manage-user-accounts.md).
### 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**
1. Go to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) in the AWS Management Console. If the console prompts you, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Sign-up** menu.
1. 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](#user-pool-settings-aliases).
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](#user-pool-settings-aliases).
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](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Username) 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³ | Yes | No |
| Can assign the same email address or phone number attribute value to more than one user | Yes⁴ | No |
¹ Available sign-in attributes are username, email address, phone number, and preferred username.
² Can sign in with email address or phone number.
³ Your user pool doesn't generate `UsernameExistsException` errors when users register with potentially-duplicate email addresses or phone numbers, but no username. This behavior is independent of **Prevent username existence errors**, which applies to sign-in, but not sign-up, operations.
⁴ Only the last user who has verified the attribute can sign in with it.
#### Option 1: Multiple sign-in attributes (alias attributes)
An attribute is an *alias* when users have a username but can also sign in with that attribute. Set up aliases when you want to allow your users to choose between their username and other attribute values in the username field of your sign-in form. The `username` attribute is a fixed value that users can't change. If you mark an attribute as an alias, users can sign in with that attribute in place of the username. You can mark the email address, phone number, and preferred username attributes as aliases. For example, if you select email address and phone number as aliases for a user pool, users in that user pool can sign in with their username, email address, or phone number, along with their password.
To choose alias attributes, select **User name** and at least one additional sign-in option when you create your user pool.
**Note**
When you configure your user pool to be case insensitive, a user can use either lowercase or uppercase letters to sign up or sign in with their alias. For more information, see [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) in the *Amazon Cognito user pools API Reference*.
If you select email address as an alias, Amazon Cognito doesn't accept a username that matches a valid email address format. Similarly, if you select phone number as an alias, Amazon Cognito doesn't accept a username for that user pool that matches a valid phone number format.
**Note**
Alias values must be unique in a user pool. If you configure an alias for an email address or phone number, the value that you provide can be in a verified state in only one account. During sign-up, if your user provides an email address or phone number as an alias value and another user has already used that alias value, registration succeeds. However, when a user tries to confirm the account with this email (or phone number) and enters the valid code, Amazon Cognito returns an `AliasExistsException` error. The error indicates to the user that an account with this email address (or phone number) already exists. At this point, the user can abandon their attempt to create the new account and instead try to reset the password for the old account. If the user continues to create the new account, your app must call the `ConfirmSignUp` API with the `forceAliasCreation` option. `ConfirmSignUp` with `forceAliasCreation` moves the alias from the previous account to the newly created account, and marks the attribute unverified in the previous account.
Phone numbers and email addresses only become active aliases for a user after your user verifies the phone numbers and email addresses. We recommend that you choose automatic verification of email addresses and phone numbers if you use them as aliases.
Choose alias attributes to prevent `UsernameExistsException` errors for email address and phone number attributes when your users sign up.
Activate the `preferred_username` attribute so that your user can change the username that they use to sign in while their `username` attribute value doesn't change. If you want to set up this user experience, submit the new `username` value as a `preferred_username` and choose `preferred_username` as an alias. Then users can sign in with the new value that they entered. If you select `preferred_username` as an alias, your user can provide the value only when they confirm an account. They can't provide the value during registration.
When the user signs up with a username, you can choose if they can sign in with one or more of the following aliases.
+ Verified email address
+ Verified phone number
+ Preferred username
After the user signs up, they can change these aliases.
**Important**
When your user pool supports sign-in with aliases and you want to authorize or look up a user, don't identify your user by any of their sign-in attributes. The fixed-value user identifier `sub` is the only consistent indicator of your user's identity.
Include the following steps when you create the user pool so that users can sign in with an alias.
------
#### [ Phone number or email address (console) ]
You must set email address and phone number as alias attributes when you create a user pool.
**To create a user pool with username aliases in the Amazon Cognito console**
1. Go to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) in the AWS Management Console. If the console prompts you, enter your AWS credentials.
1. Create a new user pool with the **Get started** or **Create user pool** button.
1. Choose application settings in **Define your application**.
1. In **Configure options** under **Options for sign-in identifiers**, select the checkbox next to **Username** and at least one of the other options, **Email** and **Phone number**.
1. Choose your alias attributes as **Required attributes for sign-up**. In the managed login sign-up form, Amazon Cognito prompts new users to provide values for required attributes.
1. Under **Add a return URL**, set up an application callback URL for redirect after managed login sign-in.
1. Choose **Create**.
------
#### [ Phone number or email address (API/SDK) ]
Create a new user pool with the [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API operation. Configure the `AliasAttributes` parameter as shown. You can remove the `email` entry if you only want phone-number aliases, or remove the `phone_number` entry if you only want email-address aliases.
```
"AliasAttributes": [
"email",
"phone_number"
],
```
------
#### [ Preferred username (API/SDK) ]
The Amazon Cognito console creates user pools without `preferred_username` as an alias. To create user pools with a `preferred_username` alias, set up user pools with [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API requests in an AWS SDK. To support the creation of preferred username attributes at sign-up, set `preferred_username` as a required attribute. In the managed login sign-up form, Amazon Cognito prompts new users to provide values for required attributes. You *can* set `preferred_username` as a required attribute in the Amazon Cognito console, but this doesn't make it available as an alias.
**Configure as an alias**
Configure `preferred_username` as an alias in the `AliasAttributes` parameter of a `CreateUserPool` request as shown. Remove any values that you don't want as alias attributes from the list.
```
"AliasAttributes": [
"email",
"phone_number",
"preferred_username"
],
```
**Configure as required**
In the managed login sign-up form, Amazon Cognito prompts new users to provide values for required attributes. Configure `preferred_username` as required in the `SchemaAttributes` parameter of a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) request.
To set preferred username as a required attribute, configure it as shown. The following example modifies the default schema of `preferred_username` to set it as required. Other schema parameters like `AttributeDataType` (defaults to `string`) and `StringAttributeConstraints` (defaults to 1-99 characters in length) assume default values.
```
"Schema": [
{
"Name": "preferred_username",
"Required": true
}
]
```
------
#### Option 2: Email address or phone number as a sign-in attribute (username attributes)
When the user signs up with an email address or phone number as their username, you can choose if they can sign up with only email addresses, only phone numbers, or either one.
To choose username attributes, don't select **Username** as a sign-in option when you create your user pool.
The email address or phone number must be unique, and it must not already be in use by another user. It doesn't have to be verified. After the user has signed up with an email address or phone number, the user can't create a new account with the same email address or phone number. The user can only reuse the existing account and reset the account password, if needed. However, the user can change the email address or phone number to a new email address or phone number. If the email address or phone number isn't already in use, it becomes the new username.
When you select both email address and phone number as username attributes, users can sign in with one or the other, even if they provide values for both attributes. The sign-in username is based on the value that you pass in the `Username` parameter of [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Username).
**Note**
If a user signs up with an email address as their username, they can change the username to another email address, but they can't change it to a phone number. If they sign up with a phone number, they can change the username to another phone number, but they can't change it to an email address.
Use the following steps during the user pool creation process to set up sign-up and sign-in with email address or phone number.
------
#### [ Username attributes (console) ]
The following procedure creates a user pool with email address or phone number username attributes. The difference in the process for username attributes in the Amazon Cognito console is that you don't also set **Username** as a sign-in attribute.
**To create a user pool with username attributes in the Amazon Cognito console**
1. Go to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) in the AWS Management Console. If the console prompts you, enter your AWS credentials.
1. Create a new user pool with the **Get started** or **Create user pool** button.
1. Choose application settings in **Define your application**.
1. In **Configure options** under **Options for sign-in identifiers**, select your username attributes: **Email**, **Phone number**, or both. Leave **Username** unchecked.
1. As a best practice, select your username attributes as **Required attributes for sign-up**. In the managed login sign-up form, Amazon Cognito prompts new users to provide values for required attributes. If you don't set your username attributes as required, Amazon Cognito doesn't prompt new users to provide values for them. In that scenario, you must configure your application to collect and submit email addresses or phone numbers for each user before they can sign in.
1. Under **Add a return URL**, set up an application callback URL for redirect after managed login sign-in.
1. Choose **Create**.
------
#### [ Username attributes (API/SDK) ]
In a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) request, configure the `UsernameAttributes` parameter as shown. To allow sign-in only with email-address usernames, specify `email` alone in this list. To allow sign-in only with phone-number usernames, specify `phone_number` alone. This parameter overrides username as a sign-in option.
```
"UsernameAttributes": [
"email",
"phone_number"
],
```
------
When you configure username attributes, your can make [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) API requests that pass an email address or phone number in the `username` parameter. The following is the behavior of the code`SignUp` API operation with username attributes.
+ If the `username` string is in valid email address format, for example `user@example.com`, the user pool automatically populates the `email` attribute of the user with the `username` value.
+ If the `username` string is in valid phone number format, for example `+12065551212`, the user pool automatically populates the `phone_number` attribute of the user with the `username` value.
+ If the `username` string format isn't in email address or phone number format, the `SignUp` API returns an exception.
+ If the `username` string contains an email address or phone number that is already in use, the `SignUp` API returns an exception.
+ The `SignUp` API populates the `username` attribute with a [UUID](cognito-terms.md#terms-uuid) for your user. This UUID has the same value as the `sub` claim in the user identity token.
You can use an email address or phone number in place of the username in all APIs except the [ListUsers](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html) operation. In `ListUsers` API requests, you can specify a `Filter` of `email` or `phone_number`. If you filter by `username`, you must supply the UUID username, not the email address or phone number.
## Custom attributes
You can add up to 50 custom attributes to your user pool. You can specify a minimum and/or maximum length for custom attributes. However, the maximum length for any custom attribute can be no more than 2048 characters. The name of a custom attribute must match the regular expression pattern that's described in the `Name` parameter of [SchemaAttributeType](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SchemaAttributeType.html).
**Each custom attribute has the following characteristics:**
+ You can define it as a string, number, boolean, or `DateTime` object. Amazon Cognito writes custom attribute values to the ID token only as strings.
**Note**
In the Amazon Cognito console, you can add custom attributes only of the string and number data types. Additional options like boolean and `DateTime` attribute data types are only available in the `SchemaAttributes` property of [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) and [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API requests.
+ You can't require that users provide a value for the attribute.
+ You can't remove or change it after you add it to the user pool.
+ The character length of the attribute name is within the limit that Amazon Cognito accepts. For more information, see [Quotas in Amazon Cognito](quotas.md).
+ It can be *mutable* or *immutable*. You can only write a value to an immutable attribute when you create a user. You can change the value of a mutable attribute if your app client has write permission to the attribute. See [Attribute permissions and scopes](#user-pool-settings-attribute-permissions-and-scopes) for more information.
**Note**
In your code, and in rules settings for [Using role-based access control](role-based-access-control.md), custom attributes require the `custom:` prefix to distinguish them from standard attributes.
You can also add *developer attributes* when you create user pools, in the `SchemaAttributes` property of [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html). Developer attributes have a `dev:` prefix. You can only modify a user's developer attributes with AWS credentials. Developer attributes are a legacy feature that Amazon Cognito replaced with app client read-write permissions.
Use the following procedure to create a new custom attribute.
**To add a custom attribute using the console**
1. Go to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) in the AWS Management Console. If the console prompts you, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **Sign-up** menu, and in the **Custom attributes** section, choose **Add custom attributes**.
1. On the **Add custom attributes** page, provide the following details about the new attribute:
+ Enter a **Name**.
+ Select a** Type** of either **String** or **Number**.
+ Enter a **Min** string length or number value.
+ Enter a **Max** string length or number value.
+ Select **Mutable** if you want to give users permission to change the value of a custom attribute after they set the initial value.
1. Choose **Save changes**.
## Attribute permissions and scopes
For each app client, you can set read and write permissions for each user attribute. This way, you can control the access that any app has to read and modify each attribute that you store for your users. For example, you might have a custom attribute that indicates whether a user is a paying customer or not. Your apps might be able to see this attribute but not change it directly. Instead, you would update this attribute using an administrative tool or a background process. You can set permissions for user attributes from the Amazon Cognito console, the Amazon Cognito API, or the AWS CLI. By default, any new custom attributes aren't available until you set read and write permissions for them. By default, when you create a new app client, you grant your app read and write permissions for all standard and custom attributes. To limit your app to only the amount of information that it requires, assign specific permissions to attributes in your app client configuration.
As a best practice, specify attribute read and write permissions when you create an app client. Grant your app client access to the minimum set of user attributes that you need for the operation of your application.
**Note**
[DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html) only returns values for `ReadAttributes` and `WriteAttributes` when you configure app client permissions other than the default.
**To update attribute permissions (AWS Management Console)**
1. Go to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) in the AWS Management Console. If the console prompts you, enter your AWS credentials.
1. Choose **User Pools**.
1. Choose an existing user pool from the list.
1. Choose the **App clients** menu and choose an app client from the list.
1. In the **Attribute permissions** tab, choose **Edit**.
1. On the **Edit attribute read and write permissions** page, configure your read and write permissions, and then choose **Save changes**.
Repeat these steps for each app client that uses the custom attribute.
For each app client, you can mark attributes as readable or writeable. This applies to both standard and custom attributes. Your app can retrieve the value of attributes that you mark as readable, and can set or modify the value of attributes that you mark as writeable. If your app tries to set a value for an attribute that it isn't authorized to write, Amazon Cognito returns `NotAuthorizedException`. [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html) requests include an access token with an app client claim; Amazon Cognito only returns values for attributes that your app client can read. Your user's ID token from an app only contains claims that correspond to the readable attributes. All app clients can write user pool required attributes. You can only set the value of an attribute in an Amazon Cognito user pools API request when you also provide a value for any required attributes that don't yet have a value.
Custom attributes have distinct features for read and write permissions. You can create them as mutable or immutable for the user pool, and you can set them as read or write attributes for any app client.
An immutable custom attribute can be updated once, during user creation. You can populate an immutable attribute with the following methods.
+ `SignUp`: A user signs up with an app client that has write access to an immutable custom attribute. They provide a value for that attribute.
+ Sign-in with a third-party IdP: A user signs in to an app client that has write access to an immutable custom attribute. Your user pool configuration for their IdP has a rule to map a provided claim to an immutable attribute. This is possible but not practical, because the user will only be able to sign in one time. On sign-in attempts after their first, Amazon Cognito rejects the attempt because of the mapping rule to a now-unwriteable attribute.
+ `AdminCreateUser`: You provide a value for an immutable attribute.
### Attribute permissions with scopes
In user pools that you configure with an AWS SDK or CDK, the REST API, or the AWS CLI, you can configure app client read or write access with the OIDC scope `oidc:profile`. The `oidc:profile` grants read or write access to the following standard attributes:
+ `name`
+ `family_name`
+ `given_name`
+ `middle_name`
+ `nickname`
+ `preferred_username`
+ `profile`
+ `picture`
+ `website`
+ `gender`
+ `birthdate`
+ `zoneinfo`
+ `locale`
This list is the OIDC standard attributes minus `email`, `phone_number`, `sub`, and `address`, as defined in [section 2.4 of the OIDC specification](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes). For information about the scopes that you can assign to your app clients, see [Scopes, M2M, and resource servers](cognito-user-pools-define-resource-servers.md).
To configure your app client to write to the attributes under the `oidc:profile` scope, set the value of [WriteAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html#CognitoUserPools-CreateUserPoolClient-request-WriteAttributes) to `oidc:profile`, plus any other attributes that you want to permit your application to modify, in a [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) or [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API request. Similarly, to grant read access to these attributes, add `oidc:profile` to the value of [ReadAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html#CognitoUserPools-CreateUserPoolClient-request-ReadAttributes).
You can change attribute permissions and scopes after you have created your user pool.