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

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version. In the following commands, replace VALID-ACCESS-TOKEN, USER-POOL-ID, CLIENT-ID, USERNAME, CONFIRMATION-CODE, NEW-PASSWORD, and PREVIOUS-PASSWORD with your values.

Change the password as the user

Note: To run the change-password command, the user must have a signed-in user's access token. The access token must include the aws.cognito.signin.user.admin scope.

To change the password as a user, run the following change-password command:

aws cognito-idp change-password --previous-password PREVIOUS-PASSWORD --proposed-password NEW-PASSWORD --access-token VALID-ACCESS-TOKEN

Reset a user password as the administrator

For an administrator to reset a user's password, the user must have a verified email or phone number in the user pool. When the administrator runs the admin-reset-user-password command, Amazon Cognito automatically sends a confirmation code to the user's verified contact method.

As the administrator, run the following admin-reset-user-password command to reset the user's password:

aws cognito-idp admin-reset-user-password --user-pool-id USER-POOL-ID --username USERNAME

Note: When the user tries to sign in after the administrator resets the password, the user receives the "PasswordResetRequiredException" error. Then, Amazon Cognito redirects the user to the forgot-password flow.

After the administrator runs the admin-reset-user-password command, the user runs the following confirm-forgot-password command to set a new password:

aws cognito-idp confirm-forgot-password --client-id CLIENT-ID --username USERNAME --confirmation-code CONFIRMATION-CODE --password NEW-PASSWORD

If the user doesn't have a verified email address or phone number, then the administrator receives the "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" error.

To resolve this issue, the administrator runs the following admin-update-user-attributes command to verify the user's contact information and set the attributes email_verified or phone_number_verified to true:

aws cognito-idp admin-update-user-attributes --user-pool-id USER-POOL-ID --username USERNAME --user-attributes Name="email_verified",Value="true"

After the administrator verifies the user's contact information, the administrator can then run the admin-reset-user-password command again. After the user receives the confirmation code, the user can run the confirm-forgot-password command to set the new password.

If the user still doesn't receive the confirmation code, then see Why doesn't Amazon Cognito send the verification code email or SMS text message with the ForgotPassword API call?

Set a permanent or temporary password as the administrator

To set a permanent password for the user, the administrator runs the following admin-set-user-password command:

aws cognito-idp admin-set-user-password --user-pool-id USER-POOL-ID --username USERNAME --password NEW-PASSWORD --permanent

Then, the user can sign in with the new permanent password.

To set a temporary password for the user, the administrator runs the following admin-set-user-password command:

aws cognito-idp admin-set-user-password --user-pool-id USER-POOL-ID --username USERNAME --password TEMPORARY-NEW-PASSWORD --no-permanent

After the administrator sets a temporary password, the user's status changes to FORCE_CHANGE_PASSWORD. After the user signs in with the temporary password, the user receives a NEW_PASSWORD_REQUIRED challenge.

Note: The session token's duration to complete the password challenge is valid for 3 minutes. You can modify the duration in your app client's authentication flow duration setting.

Then, the user runs the following respond-to-auth-challenge command to set a new password:

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

Important: If you configured your app client with a client secret, then the user must include the secret hash parameter in the respond-to-auth-challenge command to access the user pool. If the user receives the "Unable to verify secret hash for client" error, then see How do I troubleshoot "Unable to verify secret hash for client" errors from my Amazon Cognito user pools API?