Managing user existence error responses
Amazon Cognito supports customizing error responses returned by user pools. Custom error responses are available for user creation and authentication, password recovery, and confirmation operations.
Use the PreventUserExistenceErrors
setting of a user pool app client to enable
or disable user existence related errors. When you create a new user pool using the Amazon Cognito user pools API,
PreventUserExistenceErrors
is false
by default. When this value is
true
, Amazon Cognito responds with nonspecific information to API requests where its
response might otherwise disclose that a valid user exists. In the Amazon Cognito API, update this value
with a UpdateUserPoolClient request. In the AWS Management Console, create or edit your
app client to activate Prevent user existence errors. When you create a new
user pool in the AWS Management Console, Prevent user existence errors defaults to
enabled.
When you prevent user existence errors in your user pool, Amazon Cognito sign-in and forgot-password
APIs return a generic authentication failure response. The error response tells you the user
name or password is incorrect. Amazon Cognito account confirmation and password recovery APIs return a
response indicating a code was sent to a simulated delivery medium. The error response works
when the status is ENABLED
and the user doesn't exist. Following are the detailed
behaviors for the Amazon Cognito operations when PreventUserExistenceErrors
is set to
ENABLED
.
User creation and authentication operations
You can use either User name password authentication or Secure Remote Password (SRP) authentication with the following operations. You can also customize the errors that you return with custom authentication.
-
AdminInitiateAuth
-
AdminRespondToAuthChallenge
-
InitiateAuth
-
RespondToAuthChallenge
The following list demonstrates how you can customize error responses in user authentication operations.
- Username and password authentication
-
To sign a user in with
ADMIN_USER_PASSWORD_AUTH
andUSER_PASSWORD_AUTH
, include the username and password in anAdminInitiateAuth
orInitiateAuth
API request. Amazon Cognito returns a genericNotAuthorizedException
error when either the username or password is incorrect. - Secure Remote Password (SRP) based authentication
-
To sign a user in with
USER_SRP_AUTH
, include a username and anSRP_A
parameter in anAdminInitiateAuth
orInitiateAuth
API request. In response, Amazon Cognito returnsSRP_B
and salt for the user, in accord with the SRP standard. When a user isn't found, Amazon Cognito returns a simulated response in the first step as described in RFC 5054. Amazon Cognito returns the same salt and an internal user ID in Universally Unique Identifier (UUID) format for the same username and user pool combination. When you send a RespondToAuthChallenge
API request with proof of password, Amazon Cognito returns a genericNotAuthorizedException
error when either username or password is incorrect.Note
You can simulate a generic response with username and password authentication if you are using verification-based alias attributes, and the immutable username isn't formatted as a UUID.
- Custom Authentication Challenge Lambda trigger
-
If you use the Custom Authentication Challenge Lambda Trigger and you enable error responses, then
LambdaChallenge
returns a Boolean parameter namedUserNotFound
. Then it's passed in the request ofDefineAuthChallenge
,VerifyAuthChallenge
, andCreateAuthChallenge
Lambda triggers. You can use this trigger to simulate custom authorization challenges for a user that doesn't exist. If you call the Pre-Authentication Lambda trigger for a user that doesn't exist, then Amazon Cognito returnsUserNotFound
.
The following list demonstrates how you can customize error responses in user creation operations.
- SignUp
-
The
SignUp
operation returnsUsernameExistsException
when a username is already taken. If you don't want Amazon Cognito to return aUsernameExistsException
error for email addresses and phone numbers when you sign up users in your app, use verification-based alias attributes. For more information about aliases, see the Customizing sign-in attributes section of User pool attributes.For an example of how Amazon Cognito can prevent the use of
SignUp
API requests to discover users in your user pool, see Preventing UsernameExistsException errors for email addresses and phone numbers on sign-up. - Imported users
-
If
PreventUserExistenceErrors
is enabled, during authentication of imported users a genericNotAuthorizedException
error is returned indicating either the username or password was incorrect instead of returningPasswordResetRequiredException
. See Requiring imported users to reset their passwords for more information. - Migrate user Lambda trigger
-
Amazon Cognito returns a simulated response for users that don't exist when an empty response was set in the original event context by the Lambda trigger. For more information, see Migrate User Lambda Trigger.
Preventing
UsernameExistsException
errors for email addresses and phone numbers on
sign-up
The following example demonstrates how, when you configure alias attributes in your user
pool, you can keep duplicate email addresses and phone numbers from generating
UsernameExistsException
errors in response to SignUp
API
requests. You must have created your user pool with email address or phone number as an
alias attribute. For more information, see the Customizing sign-in
attributes section of User pool attributes.
-
Jie signs up for a new username, and also provides the email address
jie@example.com
. Amazon Cognito sends a code to their email address.Example AWS CLI command
aws cognito-idp sign-up --client-id 1234567890abcdef0 --username jie --password PASSWORD --user-attributes Name="email",Value="jie@example.com"
Example response
{ "UserConfirmed": false, "UserSub": "
<subId>
", "CodeDeliveryDetails": { "AttributeName": "email", "Destination": "j****@e****", "DeliveryMedium": "EMAIL" } } -
Jie provides the code sent to them to confirm their ownership of the email address. This completes their registration as a user.
Example AWS CLI command
aws cognito-idp confirm-sign-up --client-id 1234567890abcdef0 --username=jie --confirmation-code xxxxxx
-
Shirley registers a new user account and provides the email address
jie@example.com
. Amazon Cognito doesn't return aUsernameExistsException
error, and sends a confirmation code to Jie's email address.Example AWS CLI command
aws cognito-idp sign-up --client-id 1234567890abcdef0 --username shirley --password PASSWORD --user-attributes Name="email",Value="jie@example.com"
Example response
{ "UserConfirmed": false, "UserSub": "
<new subId>
", "CodeDeliveryDetails": { "AttributeName": "email", "Destination": "j****@e****", "DeliveryMedium": "EMAIL" } } -
In a different scenario, Shirley has ownership of
jie@example.com
. Shirley retrieves the code that Amazon Cognito sent to Jie's email address and attempts to confirm the account.Example AWS CLI command
aws cognito-idp confirm-sign-up --client-id 1234567890abcdef0 --username=shirley --confirmation-code xxxxxx
Example response
An error occurred (AliasExistsException) when calling the ConfirmSignUp operation: An account with the email already exists.
Amazon Cognito doesn't return an error to Shirley's aws cognito-idp sign-up
request,
despite jie@example.com
being assigned to an existing user. Shirley must
demonstrate ownership of the email address before Amazon Cognito returns an error response. In a user
pool with alias attributes, this behavior prevents use of the public SignUp
API
to check whether a user exists with a given email address or phone number.
This behavior is different from the response that Amazon Cognito returns to SignUp
request with an existing username, as shown in the following example. While Shirley learns
from this response that a user already exists with the username jie
, they don't
learn about any email addresses or phone numbers associated with the user.
Example CLI command
aws cognito-idp sign-up --client-id 1example23456789 --username jie --password PASSWORD --user-attributes Name="email",Value="shirley@example.com"
Example response
An error occurred (UsernameExistsException) when calling the SignUp operation: User already exists
Password reset operations
Amazon Cognito returns the following responses to user password reset operations when you prevent user existence errors.
- ForgotPassword
-
When a user isn't found, is deactivated, or doesn't have a verified delivery mechanism to recover their password, Amazon Cognito returns
CodeDeliveryDetails
with a simulated delivery medium for a user. The simulated delivery medium is determined by the input username format and verification settings of the user pool. - ConfirmForgotPassword
-
Amazon Cognito returns the
CodeMismatchException
error for users that don't exist or are disabled. If a code isn't requested when usingForgotPassword
, Amazon Cognito returns theExpiredCodeException
error.
Confirmation operations
Amazon Cognito returns the following responses to user confirmation and verification operations when you prevent user existence errors.
- ResendConfirmationCode
-
Amazon Cognito returns
CodeDeliveryDetails
for a disabled user or a user that doesn't exist. Amazon Cognito sends a confirmation code to the existing user's email or phone number. - ConfirmSignUp
-
ExpiredCodeException
returns if a code has expired. Amazon Cognito returnsNotAuthorizedException
when a user isn't authorized. If the code doesn't match what the server expects Amazon Cognito returnsCodeMismatchException
.