How do I reset user passwords in Amazon Cognito using the AWS CLI?

Resolution

Amazon Cognito passwords can be reset or changed by using the AWS CLI. An Amazon Cognito administrator can start a reset password flow to reset user passwords. An Amazon Cognito user can change their password on their own, or an Amazon Cognito administrator can set the user password temporarily or permanently.

Reset a user password

To start a reset passwords flow, an administrator and a user take the following steps:

1.    An administrator invokes the AdminResetUserPassword API.

Important: In these example AWS Command Line Interface (AWS CLI) commands, replace all instances of example strings with your values. (For example, replace "example_user_pool_id" with your user pool ID.)

Example admin-reset-user-password command:

aws cognito-idp admin-reset-user-password --user-pool-id example_user_pool_id --username example_user_name

2.    When a user's password is reset and the user tries to sign in, they receive a PasswordResetRequiredException exception. Then, the user is redirected to the reset password flow.

Note: The reset password flow is the same as the forgot password flow.

3.    The user with a verified email address or phone number receives a message with a confirmation code that's required to reset their password.

Work with unverified user attributes:

1.    If the user doesn't have a verified email address or phone number, then the administrator receives the following error message while invoking the AdminResetUserPassword API:

An error occurred (InvalidParameterException) when calling the AdminResetUserPassword operation: Cannot reset password for the user as there is no registered/verified email or phone_number

2.    To fix this issue, the administrator invokes the AdminUpdateUserAttributes API and sets the email_verified or phone_number_verified attributes to true.

Example admin-update-user-attributes command:

aws cognito-idp admin-update-user-attributes --user-pool-id example_user_pool_id --username example_user_name --user-attributes Name="email_verified",Value="true"

3.    If the user doesn't receive the confirmation code, then follow best practices for troubleshooting the issue.

User completes the forgot password flow:

1.    After receiving a confirmation code, the user can create a new password by invoking the ConfirmForgotPassword API.

Example confirm-forgot-password command:

aws cognito-idp confirm-forgot-password --client-id example_client_id --username example_user_name --confirmation-code example_code --password example_new password

Change a user password

Users can change their passwords on their own, and administrators set user passwords temporarily or permanently. To change a user password, a user or an administrator takes the following steps:

User changes a user password:

1.    The user invokes the ChangePassword API. The user must have valid access token issued by Amazon Cognito to invoke the ChangePassword API.

Example change-password command:

aws cognito-idp change-password --previous-password example_old_password --proposed-password example_new_password --access-token valid_access_token

Administrator creates a permanent new user password:

1.    The administrator invokes the AdminSetUserPassword API to create a new permanent password.

Example admin-set-user-password to permanently change the user password:

aws cognito-idp admin-set-user-password --user-pool-id example_user_pool_id --username example_user_name --password example_new_password --permanent

2.    After the administrator permanently changes the user password, the user can use the new password to sign in to the application.

Administrator creates a temporary new user password:

1.    The administrator invokes the AdminSetUserPassword API to create a new temporary password.

Example admin-set-user-password to temporarily change the user password:

aws cognito-idp admin-set-user-password --user-pool-id example_user_pool_id --username example_user_name --password example_temporary_password --no-permanent

If the administrator changes the user password to a temporary password, then the user must take additional steps.

2.    The user's status changes to "FORCE_CHANGE_PASSWORD" after invoking the AdminSetUserPassword API with a temporary password. A user that tries to sign in by invoking the InitiateAuth API with a temporary password receives a "NEW_PASSWORD_REQUIRED" authentication challenge.

Example initiate-auth command:

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=example_user_name,PASSWORD=example_temporary_password --client-id example_client_id

Output:

{
  "ChallengeName": "NEW_PASSWORD_REQUIRED",
  "Session": "AYA......",
  "ChallengeParameters": {
    "USER_ID_FOR_SRP": "544.....",
    "requiredAttributes": "[]",
    "userAttributes": "{\"email_verified\":\"true\",\"email\":\"user@example.com\"}"
  }
}

Note: The session token's validity depends on the Authentication flow session duration setting of your app client. By default, the session duration of this session token is 3 minutes. For modifying the token's validity, see the steps to configure the app client authentication flow session duration.

3.    The user responds to the "NEW_PASSWORD_REQUIRED" challenge by invoking the RespondToAuthChallenge API with the session token that they received in the previous step.

Example respond-to-auth-challenge command:

aws cognito-idp respond-to-auth-challenge --client-id example_client_id --challenge-name NEW_PASSWORD_REQUIRED --challenge-responses USERNAME=example_username,NEW_PASSWORD="example_new_password" --session "example_session_token"

4.    The user receives ID, access, and refresh tokens and signs in to the application.

Important: If your app client is configured with a client secret in the user pool, then you must provide the secret hash. To learn more, see How do I troubleshoot "Unable to verify secret hash for client <client-id>" errors from my Amazon Cognito user pools API?

---