Passwords, password recovery, and password policies

All users who sign in to a user pool, even federated users, have passwords assigned to their user profiles. Local users and linked users 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 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 API operation and the hosted UI 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. This is the self-service password-recovery model.

The AdminSetUserPassword and AdminResetUserPassword 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.

The AccountRecoverySetting parameter is the user pool parameter that sets the methods that users can use to recover their password when they call the ForgotPassword API. 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 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. Cognito sends a verification to only one of the specified methods.

For example, admin_only is a value used when the administrator does not want the user to recover their account themselves, and would instead require them to contact the administrator to reset their account. You cannot use admin_only with any other account recovery mechanism.

If you do not specify AccountRecoverySetting, Amazon Cognito uses the legacy mechanism to determine the password recovery method. In this case, Cognito uses a verified phone first. If the verified phone is not found for the user, Cognito falls back and will use verified email next.

For more information about AccountRecoverySetting, see CreateUserPool and UpdateUserPool in the Amazon Cognito Identity Provider API Reference.

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 advanced security features and AWS WAF web ACLs, 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 advanced security features, 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 reset access for an expired user account, do one of the following: