CAPTCHA and Challenge action behavior - Amazon WAF, Amazon Firewall Manager, and Amazon Shield Advanced
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

CAPTCHA and Challenge action behavior

When a web request matches the inspection criteria of a rule with CAPTCHA or Challenge action, Amazon WAF determines how to handle the request according to the state of its token and immunity time configuration. Amazon 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 Amazon WAF Pricing.

How the action handles the web request

Amazon WAF applies the CAPTCHA or Challenge action to a web request as follows:

  • Valid token – Amazon WAF handles this similar to a Count action. Amazon 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 web ACL.

  • Missing, invalid, or expired token – Amazon WAF discontinues the web ACL evaluation of the request and blocks it from going to its intended destination.

    Amazon WAF generates a response that it sends back to the client, according to the rule action type:

    • Challenge – Amazon WAF includes the following in the response:

      • The header x-amzn-waf-action with a value of challenge.

        Note

        This header is unavailable to JavaScript applications that run in the client browser. 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 – Amazon WAF includes the following in the response:

      • The header x-amzn-waf-action with a value of captcha.

        Note

        This header is unavailable to JavaScript applications that run in the client browser. 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 web ACL or rule level, see Timestamp expiration: Amazon WAF token immunity times.

Headers are unavailable to JavaScript applications that run in the client browser

When Amazon 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 Amazon WAF handles tokens. For information, see Amazon WAF web request tokens.