AWS cognito: Document 403 substitution for 5xx AWS WAF custom block responses
Summary
Adds a 'Status codes in custom block responses' section and related notes explaining that Amazon Cognito never returns 5xx from AWS WAF custom block responses, substituting 403 (Forbidden) while preserving custom headers/body, and clarifying behavior for managed login, classic hosted UI, and the user pools API.
Security assessment
The change documents AWS WAF custom block response behavior (status code normalization to 403) for user pools, which is security-relevant hardening/behavior guidance for WAF-protected endpoints, but it does not remediate a specific vulnerability or incident.
Evidence
+Amazon Cognito doesn't return `5xx` status codes from AWS WAF custom block responses. When a web ACL rule returns a custom block response with a status code of 500 or higher, Amazon Cognito responds with a `403 (Forbidden)` status code instead.
Diff
diff --git a/cognito/latest/developerguide/user-pool-waf.md b/cognito/latest/developerguide/user-pool-waf.md index 588096e..f9d0dcc 100644 --- a//cognito/latest/developerguide/user-pool-waf.md +++ b//cognito/latest/developerguide/user-pool-waf.md @@ -7 +7 @@ -Things to know about AWS WAF web ACLs and Amazon CognitoContent-Security-Policy on custom block responsesAssociating a web ACL with your user poolTesting and logging AWS WAF web ACLs +Things to know about AWS WAF web ACLs and Amazon CognitoContent-Security-Policy on custom block responsesStatus codes in custom block responsesAssociating a web ACL with your user poolTesting and logging AWS WAF web ACLs @@ -21 +21 @@ When you have an AWS WAF web ACL associated with a user pool, Amazon Cognito for - * Web ACL rule conditions can only return custom block responses to users' **first** request to a user-interactive managed login page. When subsequent connections match a custom block response condition, they return your custom status code, header, and redirect responses, but a default block message. + * Web ACL rules can return your custom block response only when the browser loads a managed login page. Requests that the page sends without reloading, such as when a user submits the sign-in form, receive a default `403` block response instead. @@ -36,0 +37,2 @@ When you have an AWS WAF web ACL associated with a user pool, Amazon Cognito for + * When a rule in your web ACL returns a custom block response with an HTTP status code of 500 or higher in response to a managed login or classic hosted UI request, Amazon Cognito returns a `403 (Forbidden)` status code instead. For more information, see Status codes in custom block responses. + @@ -58 +60 @@ Your options to customize the error response depends on the way you make an API - * You can customize the error code and response body of managed login requests. You can only present a CAPTCHA for your user to solve in managed login. + * You can customize the error code and response body of managed login requests. Amazon Cognito returns custom error codes of 500 and higher as `403`. For more information, see Status codes in custom block responses. You can only present a CAPTCHA for your user to solve in managed login. @@ -83,0 +86,13 @@ This behavior applies in all AWS Regions where you can associate a web ACL with +## Status codes in custom block responses + +Amazon Cognito doesn't return `5xx` status codes from AWS WAF custom block responses. When a web ACL rule returns a custom block response with a status code of 500 or higher, Amazon Cognito responds with a `403 (Forbidden)` status code instead. The response still includes the headers and body from your custom response. This behavior applies as follows: + + * **Managed login pages** – When the browser loads a managed login page, Amazon Cognito returns `403` with the headers and body from your custom response. Requests that the page sends without reloading, such as form submissions, receive the default `403` block response without your custom headers or body. + + * **Classic hosted UI pages and other user pool endpoints** – Amazon Cognito returns `403` with the headers and body from your custom response for classic hosted UI pages. The [identity provider and relying party endpoints](./federation-endpoints.html) behave the same way, whether your user pool uses managed login or classic hosted UI branding. + + * **User pools API** – The user pools API returns your custom status code only when it's in the range 400–499, and returns `403` for other status codes. + + + +