AWS cognito high security documentation change
Summary
Updated documentation for PreventUserExistenceErrors configuration with detailed behavior across authentication flows, Lambda triggers, and user creation scenarios. Added specifics about challenge-based authentication behavior and UserNotFound parameter handling in Lambda functions.
Security assessment
Changes explicitly document how to prevent user enumeration attacks by suppressing user existence disclosure in error responses. Specific security-related details include simulated SRP responses per RFC 5054, UserNotFound parameter in Lambda triggers, and generic error responses to prevent distinguishing between invalid users and invalid credentials.
Diff
diff --git a/cognito/latest/developerguide/cognito-user-pool-managing-errors.md b/cognito/latest/developerguide/cognito-user-pool-managing-errors.md index a729d141b..9f04650bf 100644 --- a/cognito/latest/developerguide/cognito-user-pool-managing-errors.md +++ b/cognito/latest/developerguide/cognito-user-pool-managing-errors.md @@ -22 +22 @@ When this property has a value of `LEGACY`, your app client returns a `UserNotFo -When this property has a value of `ENABLED`, your app client doesn't disclose the nonexistence of a user account in your user pool with a `UserNotFoundException` error. A `PreventUserExistenceErrors` configuration of `ENABLED` has the following effects: +When this property has a value of `ENABLED`, your app client doesn't disclose the nonexistence of a user account in your user pool with a `UserNotFoundException` error. A `PreventUserExistenceErrors` configuration of `ENABLED` has the following effects when you submit a request for a username that doesn't exist: @@ -26 +26,3 @@ When this property has a value of `ENABLED`, your app client doesn't disclose th - * 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 returns a generic authentication failure response to forgot-password requests, and to authentication requests with authentication flows _except_ for [choice-based authentication](./authentication-flows-selection-sdk.html#authentication-flows-selection-choice) (`USER_AUTH`)—for example, `USER_SRP_AUTH` or `CUSTOM_AUTH`. The error response tells you the user name or password is incorrect. + + * Amazon Cognito responds to requests for choice-based authentication with a random selection from the challenge types allowed for the user pool. Your user pool might return a passkey, one-time password, or password challenge. @@ -37,9 +39 @@ The following information details the behaviors of user pool operations when `Pr -You can configure error responses in both _Username-password_ and _Secure Remote Password (SRP)_ authentication. You can also customize the errors that you return with custom authentication. The following APIs perform these authentication operations: - - * `AdminInitiateAuth` - - * `AdminRespondToAuthChallenge` - - * `InitiateAuth` - - * `RespondToAuthChallenge` +You can configure error responses in username-password, and Secure Remote Password (SRP) authentication. You can also customize the errors that you return with custom authentication. Choice-based authentication is unaffected by your `PreventUserExistenceErrors` configuration. @@ -46,0 +41 @@ You can configure error responses in both _Username-password_ and _Secure Remote +###### User-existence disclosure details in authentication flows @@ -47,0 +43 @@ You can configure error responses in both _Username-password_ and _Secure Remote +**Choice-based authentication** @@ -50 +46 @@ You can configure error responses in both _Username-password_ and _Secure Remote -The following list demonstrates how you can customize error responses in user authentication operations. +In the `USER_AUTH` choice-based authentication flow, Amazon Cognito returns a challenge from the primary authentication factors that are available, depending on your user pool configuration and users' attributes. This authentication flow can return password, secure remote password (SRP), WebAuthn (passkey), SMS one-time password (OTP), or email OTP challenges. With `PreventUserExistenceErrors` active, Amazon Cognito issues a challenge to nonexistent users to complete one or more of the available forms of authentication. With `PreventUserExistenceErrors` inactive, Amazon Cognito returns a `UserNotFound` exception. @@ -55 +51 @@ The following list demonstrates how you can customize error responses in user au -To sign a user in with `ADMIN_USER_PASSWORD_AUTH` and `USER_PASSWORD_AUTH`, include the username and password in an `AdminInitiateAuth` or `InitiateAuth` API request. Amazon Cognito returns a generic `NotAuthorizedException` error when either the username or password is incorrect. +The authentication flows `ADMIN_USER_PASSWORD_AUTH`, `USER_PASSWORD_AUTH`, and the `PASSWORD` flow of `USER_AUTH` return a `NotAuthorizedException` with the message `Incorrect username or password` when `PreventUserExistenceErrors` is active. When `PreventUserExistenceErrors` is inactive, these flows return `UserNotFoundException`. @@ -60 +56 @@ To sign a user in with `ADMIN_USER_PASSWORD_AUTH` and `USER_PASSWORD_AUTH`, incl -As a best practice, only implement `PreventUserExistenceErrors` with SRP authentication in user pools without email address, phone number, or preferred username [alias attributes](./user-pool-settings-attributes.html#user-pool-settings-aliases). Users with alias attributes might not be subject to user-existence suppression in the SRP authentication flow. Username-password authentication fully suppresses the existence of users from alias attributes. +As a best practice, only implement `PreventUserExistenceErrors` with `USER_SRP_AUTH` or the `PASSWORD_SRP` flow of `USER_AUTH` in user pools without email address, phone number, or preferred username [alias attributes](./user-pool-settings-attributes.html#user-pool-settings-aliases). Users with alias attributes might not be subject to user-existence suppression in the SRP authentication flow. Username-password authentication flows—`ADMIN_USER_PASSWORD_AUTH`, `USER_PASSWORD_AUTH`, and the `USER_AUTH` `PASSWORD` challenge—fully suppress the existence of users from alias attributes. @@ -62 +58 @@ As a best practice, only implement `PreventUserExistenceErrors` with SRP authent -To sign a user in with `USER_SRP_AUTH`, include a username and an `SRP_A` parameter in an `AdminInitiateAuth` or `InitiateAuth` API request. In response, Amazon Cognito returns `SRP_B` and salt for the user. When a user isn't found, Amazon Cognito returns a simulated response in the first step as described in [RFC 5054](https://tools.ietf.org/html/rfc5054#section-2.5.1.3). Amazon Cognito returns the same salt and an internal user ID in [UUID](./cognito-terms.html#terms-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 generic `NotAuthorizedException` error when either username or password is incorrect. +When someone attempts SRP sign-in with a username that isn't known to your app client, Amazon Cognito returns a simulated response in the first step as described in [RFC 5054](https://tools.ietf.org/html/rfc5054#section-2.5.1.3). Amazon Cognito returns the same salt and an internal user ID in [UUID](./cognito-terms.html#terms-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 generic `NotAuthorizedException` error when either username or password is incorrect. For more information about implementation of SRP authentication, see [Sign-in with persistent passwords and secure payload](./amazon-cognito-user-pools-authentication-flow-methods.html#amazon-cognito-user-pools-authentication-flow-methods-srp). @@ -68 +64,7 @@ You can simulate a generic response with username and password authentication if -**Custom Authentication Challenge Lambda trigger** +**Custom authentication challenge Lambda trigger** + + +Amazon Cognito invokes the [custom authentication challenge Lambda triggers](./user-pool-lambda-challenge.html) when users attempt to sign in with the `CUSTOM_AUTH` authentication flow, but their username isn't found. The input event includes a boolean parameter named `UserNotFound` with a value of `true` for any nonexistent user. This parameter appears in the request events that your user pool sends to the create, define, and verify auth challenge Lambda functions that make up the custom-authentication architecture. When you examine this indicator in the logic of your Lambda function, you can simulate custom authentication challenges for a user that doesn't exist. + +**Pre authentication Lambda trigger** + @@ -69,0 +72 @@ You can simulate a generic response with username and password authentication if +Amazon Cognito invokes the [pre authentication trigger](./user-pool-lambda-pre-authentication.html) when users attempt to sign in but their username isn't found. The input event includes a `UserNotFound` parameter with a value of `true` for any nonexistent user. @@ -71 +74 @@ You can simulate a generic response with username and password authentication if -If you use the [Custom Authentication Challenge Lambda Trigger](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-challenge.html) and you enable error responses, then `LambdaChallenge` returns a Boolean parameter named `UserNotFound`. Then it's passed in the request of `DefineAuthChallenge`, `VerifyAuthChallenge`, and `CreateAuthChallenge` 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 returns `UserNotFound`. +The following list describes the effect of `PreventUserExistenceErrors` on user account creation. @@ -73 +76 @@ If you use the [Custom Authentication Challenge Lambda Trigger](https://docs.aws -The following list demonstrates how you can customize error responses in user creation operations. +###### User-existence disclosure details in user creation flows @@ -85 +88 @@ For an example of how Amazon Cognito can prevent the use of `SignUp` API request -If `PreventUserExistenceErrors` is enabled, during authentication of imported users a generic `NotAuthorizedException` error is returned indicating either the username or password was incorrect instead of returning `PasswordResetRequiredException`. See [Requiring imported users to reset their passwords](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-using-import-tool-password-reset.html) for more information. +If `PreventUserExistenceErrors` is enabled, during authentication of imported users a generic `NotAuthorizedException` error is returned indicating either the username or password was incorrect instead of returning `PasswordResetRequiredException`. See [Requiring imported users to reset their passwords](./cognito-user-pools-using-import-tool.html#cognito-user-pools-using-import-tool-password-reset) for more information. @@ -90 +93 @@ If `PreventUserExistenceErrors` is enabled, during authentication of imported us -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](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html). +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 [Importing users with a user migration Lambda trigger](./cognito-user-pools-import-using-lambda.html).