**Introducing a new console experience for AWS WAF** You can now use the updated experience to access AWS WAF functionality anywhere in the console. For more details, see [Working with the console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). # CAPTCHA and Challenge in AWS WAF CAPTCHA and ChallengeAWS WAF new Challenge rule action option You can configure rules to use a Challenge, to verify that requests are being sent by browsers. AWS WAF new CAPTCHA rule action option You can configure rules to run a CAPTCHA against web requests and, as needed, send a CAPTCHA problem to the client. CAPTCHA and Challenge actions Added clarification that browser clients require HTTPS to run CAPTCHA puzzles and silent challenges. This section explains how CAPTCHA and Challenge work with AWS WAF. You can configure your AWS WAF rules to run a CAPTCHA or Challenge action against web requests that match your rule's inspection criteria. You can also program your JavaScript client applications to run CAPTCHA puzzles and browser challenges locally. CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. + **CAPTCHA** – Requires the end user to solve a CAPTCHA puzzle to prove that a human being is sending the request. CAPTCHA puzzles are intended to be fairly easy and quick for humans to complete successfully and hard for computers to either complete successfully or to randomly complete with any meaningful rate of success. In protection pack (web ACL) rules, CAPTCHA is commonly used when a Block action would stop too many legitimate requests, but letting all traffic through would result in unacceptably high levels of unwanted requests, such as from bots. For information about the rule action behavior, see [How the AWS WAF CAPTCHA and Challenge rule actions work](waf-captcha-and-challenge-how-it-works.md). You can also program a CAPTCHA puzzle implementation in your client application integration APIs. When you do this, you can customize the behavior and placement of the puzzle in your client application. For more information, see [Client application integrations in AWS WAF](waf-application-integration.md). + **Challenge** – Runs a silent challenge that requires the client session to verify that it's a browser, and not a bot. The verification runs in the background without involving the end user. This is a good option for verifying clients that you suspect of being invalid without negatively impacting the end user experience with a CAPTCHA puzzle. For information about the rule action behavior, see [How the AWS WAF CAPTCHA and Challenge rule actions work](waf-captcha-and-challenge-how-it-works.md). The Challenge rule action is similar to the challenge run by the client intelligent threat integration APIs, described at [Client application integrations in AWS WAF](waf-application-integration.md). **Note** You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). For descriptions of all of the rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md). **Topics** + [ # AWS WAF CAPTCHA puzzles ](waf-captcha-puzzle.md) + [ # How the AWS WAF CAPTCHA and Challenge rule actions work ](waf-captcha-and-challenge-how-it-works.md) + [ # Best practices for using the CAPTCHA and Challenge actions ](waf-captcha-and-challenge-best-practices.md) # AWS WAF CAPTCHA puzzles CAPTCHA puzzlesExpansion of language options for the AWS WAF CAPTCHA puzzle The CAPTCHA puzzle now offers its written instructions in multiple languages. The instructions inside each audio puzzle are still provided in English only. This section explains the features and functionality of the AWS WAF CAPTCHA puzzle. AWS WAF provides standard CAPTCHA functionality that challenges users to confirm that they are human beings. CAPTCHA stands for Completely Automated Public Turing test to tell Computers and Humans Apart. CAPTCHA puzzles are designed to verify that a human is sending requests and to prevent activity like web scraping, credential stuffing, and spam. CAPTCHA puzzles can't weed out all unwanted requests. Many puzzles have been solved using machine learning and artificial intelligence. In an effort to circumvent CAPTCHA, some organizations supplement automated techniques with human intervention. In spite of this, CAPTCHA continues to be a useful tool to prevent less sophisticated bot traffic and to increase the resources required for large-scale operations. AWS WAF randomly generates its CAPTCHA puzzles and rotates through them to ensure that users are presented with unique challenges. AWS WAF regularly adds new types and styles of puzzles to remain effective against automation techniques. In addition to the puzzles, the AWS WAF CAPTCHA script gathers data about the client to ensure that the task is being completed by a human and to prevent replay attacks. Each CAPTCHA puzzle includes a standard set of controls for the end user to request a new puzzle, switch between audio and visual puzzles, access additional instructions, and submit a puzzle solution. All puzzles include support for screen readers, keyboard controls, and contrasting colors. The AWS WAF CAPTCHA puzzles meet the requirements of the Web Content Accessibility Guidelines (WCAG). For information, see [Web Content Accessibility Guidelines (WCAG) Overview](https://www.w3.org/WAI/standards-guidelines/wcag/) at the World Wide Web Consortium (W3C) website. **Topics** + [ # CAPTCHA puzzle language support ](waf-captcha-puzzle-language-support.md) + [ # CAPTCHA puzzle examples ](waf-captcha-puzzle-examples.md) # CAPTCHA puzzle language support Language supportAWS WAF CAPTCHA puzzles audio The audio version of the CAPTCHA puzzle now supports multiple languages. This section lists what languages are supported in AWS WAF CAPTCHA puzzles. The CAPTCHA puzzle starts with written instructions in the client browser language or, if the browser language is unsupported, in English. The puzzle provides alternate language options through a dropdown menu. The user can switch to audio instructions by selecting the headphone icon at the bottom of the page. The audio version of the puzzle provides spoken instructions about text that the user should type into a text box, overlaid by background noise. The following table lists the languages that you can select for the written instructions in a CAPTCHA puzzle and the audio support for each selection. **AWS WAF CAPTCHA puzzle supported languages** | Written instructions support | Locale code | Audio instructions support | | --- | --- | --- | | Arabic | ar-SA | Arabic | | Simplified Chinese | zh-CN | Audio in English | | Dutch | nl-NL | Dutch | | English | en-US | English | | French | fr-FR | French | | German | de-DE | German | | Italian | it-IT | Italian | | Japanese | ja-JP | Audio in English | | Brazilian Portuguese | pt-BR | Brazilian Portuguese | | Spanish | es-ES | Spanish | | Turkish | tr-TR | Turkish | # CAPTCHA puzzle examples Puzzle examples A typical visual CAPTCHA puzzle requires interaction to show that the user can comprehend and interact with one or more images. The following screenshot shows an example of a picture grid puzzle. This puzzle requires you to select all of the pictures in the grid that include a specific type of object. ![\[A screen contains the title "Let's confirm you are human" and the text "Choose all the chairs". Below the text is a 3x3 grid of images, some of which contain chairs and others that contain non-chair objects, like beds and windows. At the bottom of the screen are options to load a different puzzle, toggle the information box into and out of view, toggle to an audio puzzle, and change the language. Also at the bottom is the button "Confirm".\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/CAPTCHAPuzzleGrid.png) An audio puzzle provides background noise overlaid with spoken instructions about text that the user should type into a text box. The following screenshot shows the display for the audio puzzle choice. ![\[A screen contains the title "Solve the puzzle" and the text "Click play to listen to instructions". Below the text is an image that shows a Play button. Below the image is the text "Keyboard audio toggle: alt + space". Below is a title "Enter your response" with a text entry box below it. An open information box has the text "Solve by listening to the recording and typing your answer into the text box." At the bottom of the screen are options to load a different puzzle, toggle the information box into and out of view, and toggle to a visual puzzle. Also at the bottom is the button "Submit".\]](http://docs.aws.amazon.com/waf/latest/developerguide/images/CAPTCHAPuzzleAudio.png) # How the AWS WAF CAPTCHA and Challenge rule actions work How the rule actions work This section explains how CAPTCHA and Challenge work. AWS WAF CAPTCHA and Challenge are standard rule actions, so they're relatively easy to implement. To use either of them, you create the inspection criteria for your rule that identifies the requests that you want to inspect, and then specify one of the two rule actions. For general information about rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md). In addition to implementing silent challenges and CAPTCHA puzzles from the server side, you can integrate silent challenges in your JavaScript and iOS and Android client applications, and you can render CAPTCHA puzzles in your JavaScript clients. These integrations allow you to provide your end users with better performance and CAPTCHA puzzle experiences, and they can reduce costs associated with using the rule actions and the intelligent threat mitigation rule groups. For more information about these options, see [Client application integrations in AWS WAF](waf-application-integration.md). For pricing information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). **Topics** + [ # CAPTCHA and Challenge action behavior ](waf-captcha-and-challenge-actions.md) + [ # CAPTCHA and Challenge actions in the logs and metrics ](waf-captcha-and-challenge-logs-metrics.md) # CAPTCHA and Challenge action behavior Action behavior This section explains what the CAPTCHA and Challenge actions do. When a web request matches the inspection criteria of a rule with CAPTCHA or Challenge action, AWS WAF determines how to handle the request according to the state of its token and immunity time configuration. AWS WAF also considers whether the request can handle the CAPTCHA puzzle or challenge script interstitials. The scripts are designed to be handled as HTML content, and they can only be handled properly by a client that's expecting HTML content. **Note** You are charged additional fees when you use the CAPTCHA or Challenge rule action in one of your rules or as a rule action override in a rule group. For more information, see [AWS WAF Pricing](https://aws.amazon.com/waf/pricing/). **How the action handles the web request** AWS WAF applies the CAPTCHA or Challenge action to a web request as follows: + **Valid token** – AWS WAF handles this similar to a Count action. AWS WAF applies any labels and request customizations that you've configured for the rule action, and then continues evaluating the request using the remaining rules in the protection pack (web ACL). + **Missing, invalid, or expired token** – AWS WAF discontinues the protection pack (web ACL) evaluation of the request and blocks it from going to its intended destination. AWS WAF generates a response that it sends back to the client, according to the rule action type: + **Challenge** – AWS WAF includes the following in the response: + The header `x-amzn-waf-action` with a value of `challenge`. **Note** For Javascript applications running in the client browser, this header is only available within the application's domain. The header isn't available for cross-domain retrieval. For details, see the section that follows. + The HTTP status code `202 Request Accepted`. + If the request contains an `Accept` header with a value of `text/html`, the response includes a JavaScript page interstitial with a challenge script. + **CAPTCHA** – AWS WAF includes the following in the response: + The header `x-amzn-waf-action` with a value of `captcha`. **Note** For Javascript applications running in the client browser, this header is only available within the application's domain. The header isn't available for cross-domain retrieval. For details, see the section that follows. + The HTTP status code `405 Method Not Allowed`. + If the request contains an `Accept` header with a value of `text/html`, the response includes a JavaScript page interstitial with a CAPTCHA script. To configure the timing of token expiration at the protection pack (web ACL) or rule level, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md). **Headers are unavailable to JavaScript applications that run in the client browser** When AWS WAF responds to a client request with a CAPTCHA or challenge response, it doesn't include cross-origin resource sharing (CORS) headers. CORS headers are a set of access control headers that tell the client web browser which domains, HTTP methods, and HTTP headers can be used by JavaScript applications. Without CORS headers, JavaScript applications running in a client browser are not granted access to HTTP headers and so are unable to read the `x-amzn-waf-action` header that's provided in the CAPTCHA and Challenge responses. **What the challenge and CAPTCHA interstitials do** When a challenge interstitial runs, after the client responds successfully, if it doesn't already have a token, the interstitial initializes one for it. Then it updates the token with the challenge solve timestamp. When a CAPTCHA interstitial runs, if the client doesn't have a token yet, the CAPTCHA interstitial invokes the challenge script first to challenge the browser and initialize the token. Then the interstitial runs its CAPTCHA puzzle. When the end user successfully completes the puzzle, the interstitial updates the token with the CAPTCHA solve timestamp. In either case, after the client responds successfully and the script updates the token, the script resubmits the original web request using the updated token. You can configure how AWS WAF handles tokens. For information, see [Token use in AWS WAF intelligent threat mitigation](waf-tokens.md). # CAPTCHA and Challenge actions in the logs and metrics Logs and metrics This section explains how AWS WAF handles logging and metrics for the CAPTCHA and Challenge actions. The CAPTCHA and Challenge actions can be non-terminating, like Count, or terminating, like Block. The outcome depends on whether the request has a valid token with an unexpired timestamp for the action type. + **Valid token** – When the action finds a valid token and doesn't block the request, AWS WAF captures metrics and logs as follows: + Increments the metrics for either `CaptchaRequests` and `RequestsWithValidCaptchaToken` or `ChallengeRequests` and `RequestsWithValidChallengeToken`. + Logs the match as a `nonTerminatingMatchingRules` entry with action of CAPTCHA or Challenge. The following listing shows the section of a log for this type of match with the CAPTCHA action. ``` "nonTerminatingMatchingRules": [ { "ruleId": "captcha-rule", "action": "CAPTCHA", "ruleMatchDetails": [], "captchaResponse": { "responseCode": 0, "solveTimestamp": 1632420429 } } ] ``` + **Missing, invalid, or expired token** – When the action blocks the request due to a missing or invalid token, AWS WAF captures metrics and logs as follows: + Increments the metric for `CaptchaRequests` or `ChallengeRequests`. + Logs the match as a `CaptchaResponse` entry with HTTP `405` status code or as a `ChallengeResponse` entry with HTTP `202` status code. The log indicates whether the request was missing the token or had an expired timestamp. The log also indicates whether AWS WAF sent a CAPTCHA interstitial page to the client or a silent challenge to the client browser. The following listing shows the sections of a log for this type of match with the CAPTCHA action. ``` "terminatingRuleId": "captcha-rule", "terminatingRuleType": "REGULAR", "action": "CAPTCHA", "terminatingRuleMatchDetails": [], ... "responseCodeSent": 405, ... "captchaResponse": { "responseCode": 405, "solveTimestamp": 0, "failureReason": "TOKEN_MISSING" } ``` For information about the AWS WAF logs, see [Logging AWS WAF protection pack (web ACL) traffic](logging.md). For information about AWS WAF metrics, see [AWS WAF metrics and dimensions](waf-metrics.md). For general information about rule action options, see [Using rule actions in AWS WAF](waf-rule-action.md). **Requests with no token seem to show up twice in logs and metrics** Based on the [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md) and the logging and metrics described in this section, a request with no token will generally be represented twice in the logs and metrics. This is because the one intended request is actually sent twice by the client. + The first request, with no token, receives the logging and metrics handling described above for missing, invalid, or expired token. The CAPTCHA or Challenge action terminates this first request, and then responds back to the client with either a silent challenge or CAPTCHA puzzle. + The client evaluates the challenge or puzzle and, if the client browser or end user responds successfully, sends the request a second time with the newly acquired token. This second request receives the logging and metrics handling described above for a request with a valid token. # Best practices for using the CAPTCHA and Challenge actions CAPTCHA and Challenge best practices Follow the guidance in this section to plan and implement AWS WAF CAPTCHA or challenge. **Plan your CAPTCHA and challenge implementation** Determine where to place CAPTCHA puzzles or silent challenges based on your website usage, the sensitivity of the data that you want to protect, and the type of requests. Select the requests where you'll apply CAPTCHA so that you present the puzzles as needed, but avoid presenting them where they wouldn't be useful and might degrade the user experience. Use the Challenge action to run silent challenges that have less impact on the end user, but still help verify that the request is coming from a JavaScript enabled browser. CAPTCHA puzzles and silent challenges can only run when browsers are accessing HTTPS endpoints. Browser clients must be running in secure contexts in order to acquire tokens. **Decide where to run CAPTCHA puzzles and silent challenges on your clients** Identify requests that you don't want to have impacted by CAPTCHA, for example, requests for CSS or images. Use CAPTCHA only when necessary. For example, if you plan to have a CAPTCHA check at login, and the user is always taken directly from the login to another screen, requiring a CAPTCHA check at the second screen would probably not be needed and might degrade your end user experience. Configure your Challenge and CAPTCHA use so that AWS WAF only sends CAPTCHA puzzles and silent challenges in response to `GET` `text/html` requests. You can't run either the puzzle or the challenge in response to `POST` requests, Cross-Origin Resource Sharing (CORS) preflight `OPTIONS` requests, or any other non-`GET` request types. Browser behavior for other request types can vary and might not be able to handle the interstitials properly. It's possible for a client to accept HTML but still not be able to handle the CAPTCHA or challenge interstitial. For example, a widget on a webpage with a small iFrame might accept HTML but not be able to display a CAPTCHA or process it. Avoid placing the rule actions for these types of requests, the same as for requests that don't accept HTML. **Use CAPTCHA or Challenge to verify prior token acquisition** You can use the rule actions solely to verify the existence of a valid token, at locations where legitimate users should always have one. In these situations, it doesn't matter whether the request can handle the interstitials. For example, if you implement the JavaScript client application CAPTCHA API, and run the CAPTCHA puzzle on the client immediately before you send the first request to your protected endpoint, your first request should always include a token that's valid for both challenge and CAPTCHA. For information about JavaScript client application integration, see [AWS WAF JavaScript integrations](waf-javascript-api.md). For this situation, in your protection pack (web ACL), you can add a rule that matches against this first call and configure it with the Challenge or CAPTCHA rule action. When the rule matches for a legitimate end user and browser, the action will find a valid token, and therefore will not block the request or send a challenge or CAPTCHA puzzle in response. For more information about how the rule actions work, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md). **Protect your sensitive non-HTML data with CAPTCHA and Challenge** You can use CAPTCHA and Challenge protections for sensitive non-HTML data, like APIs, with the following approach. 1. Identify requests that take HTML responses and that are run in close proximity to the requests for your sensitive, non-HTML data. 1. Write CAPTCHA or Challenge rules that match against the requests for HTML and that match against the requests for your sensitive data. 1. Tune your CAPTCHA and Challenge immunity time settings so that, for normal user interactions, the tokens that clients obtain from the HTML requests are available and unexpired in their requests for your sensitive data. For tuning information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md). When a request for your sensitive data matches a CAPTCHA or Challenge rule, it won't be blocked if the client still has a valid token from the prior puzzle or challenge. If the token isn't available or the timestamp is expired, the request to access your sensitive data will fail. For more information about how the rule actions work, see [CAPTCHA and Challenge action behavior](waf-captcha-and-challenge-actions.md). **Use CAPTCHA and Challenge to tune your existing rules** Review your existing rules, to see if you want to alter or add to them. The following are some common scenarios to consider. + If you have a rate-based rule that blocks traffic, but you keep the rate limit relatively high to avoid blocking legitimate users, consider adding a second rate-based rule after the blocking rule. Give the second rule a lower limit than the blocking rule and set the rule action to CAPTCHA or Challenge. The blocking rule will still block requests that are coming at too high a rate, and the new rule will block most automated traffic at an even lower rate. For information about rate-based rules, see [Using rate-based rule statements in AWS WAF](waf-rule-statement-type-rate-based.md). + If you have a managed rule group that blocks requests, you can switch the behavior for some or all of the rules from Block to CAPTCHA or Challenge. To do this, in the managed rule group configuration, override the rule action setting. For information about overriding rule actions, see [Rule group rule action overrides](web-acl-rule-group-override-options.md#web-acl-rule-group-override-options-rules). **Test your CAPTCHA and challenge implementations before you deploy them** As for all new functionality, follow the guidance at [Testing and tuning your AWS WAF protections](web-acl-testing.md). During testing, review your token timestamp expiration requirements and set your web ACL and rule level immunity time configurations so that you achieve a good balance between controlling access to your website and providing a good experience for your customers. For information, see [Setting timestamp expiration and token immunity times in AWS WAF](waf-tokens-immunity-times.md).