Managing Error Response - Amazon Cognito

Managing Error Response

You can customize the errors and responses returned by Cognito User Pools during authentication, confirmation, and password recovery related operations when the user does not exist. By using the PreventUserExistenceErrors setting of a user pool app client, you can customize whether to throw user existence related errors. If the setting is not enabled or set to LEGACY, the Cognito authentication, confirmation and password recovery operations return a UserNotFoundException when a non existing username is provided in input.

When this setting is enabled, Cognito authentication APIs return a generic authentication failure response that indicates either the username or password was incorrect. Cognito account confirmation and password recovery APIs return a response indicating a code was sent to a simulated delivery medium when the setting is enabled and the user does not exist. Below is the detailed behaviors for the Cognito operations when PreventUserExistenceErrors is set to ENABLED:

  • User authentication operations : Such operations include; AdminInitiateAuth, AdminRespondToAuthChallenge, InitiateAuth, and RespondToAuthChallenge. Authentication can be done using either authentication flow methods:

    • Username password based authentication - In these authentication flows (ADMIN_USER_PASSWORD_AUTH, and USER_PASSWORD_AUTH), the username and password is received in a single call of InitiateAuth. Cognito returns a generic NotAuthorizedException error indicating either username or password was incorrect. If a user is disabled and the password is incorrect, the error will also indicate that either the username or password is incorrect.

    • SRP based authentication - In these authentication flows (USER_SRP_AUTH), the Cognito service receives a username and SRP parameter ‘A’ in the first step. In response, Cognito returns SRP parameter ‘B’ and ‘salt’ for the user as per SRP protocol. When a user is not found, Cognito returns a simulated response in the first step as described in RFC 5054. Cognito consistently returns the same ‘salt’, and an internal user id in UUID format for the same username and user pool combination. In the next operation of RespondToAuthChallenge when the proof of password is provided then Cognito returns a generic NotAuthorizedException error indicating either username or password was incorrect. Please note that, if you are using verification based aliases which supports multiple username scenarios and the format of immutable username is not a UUID then preferred setting is to use ‘Username password based authentication’ to simulate a generic response.

  • ForgotPassword : When a user is not found, is disabled, or does not have a mechanism to recover their password, Cognito returns a CodeDeliveryDetails with a simulated delivery medium consistently for a user. The simulated delivery medium is determined by the input username format and verification settings of the user pool.

  • ConfirmForgotPassword : For a non existing or disabled user Cognito returns the CodeMismatchException error. If no code is requested in previous step by using ForgotPassword, Cognito returns the ExpiredCodeException error.

  • ResendConfirmationCode : For a non existing or disabled user, Cognito returns a simulated CodeDeliveryDetails consistently for a user. The simulated delivery medium is determined by the input username format and verification settings of the user pool. For an existing user, Cognito sends a confirmation code to the user email or phone.

  • ConfirmSignUp : For a non existing or disabled user, Cognito returns ExpiredCodeException. If a user is already confirmed and the provided code is valid then NotAuthorizedException error is returned describing that account is already confirmed. Else, if the code is invalid, the CodeMismatchException error is returned.

Note

After February 15th 2020, the value of PreventUserExistenceErrors will default to ENABLED for newly created User Pool Clients if no value is provided.

Regardless of the value of PreventUserExistenceErrors, the SignUp operation continues to return UsernameExistsException when a username is already taken. To prevent the UsernameExistsException error for email or phone number during SignUp, you can use verification based aliases. For more information, see AliasAttributes in the Amazon Cognito User Pools API Reference.

This allows SignUp to succeed even when an account with the given email exists but UsernameExistsException is returned during ConfirmSignUp only when a correct verification code is provided. For more information, see Overview of Aliases.

With user migration Lambda trigger, Cognito will return a simulated response for non existing users when an empty response was set in the original event context by the Lambda trigger. For more information, see Migrate User Lambda Trigger.

If you are using Custom Authentication Challenge Lambda Triggers and enable this new setting, a new boolean parameter named userNotFound is passed in the request of the DefineAuthChalleng, VerifyAuthChallenge and CreateAuthChallenge Lambda triggers. You can use this to simulate custom auth challenges for non existing users. Similarly, Pre-Authentication Lambda trigger is called for non existing users and a boolean parameter named userNotFound is passed in the request.