Using the CAPTCHA JavaScript API - 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).

Using the CAPTCHA JavaScript API

The CAPTCHA JavaScript API allows you to configure the CAPTCHA puzzle and place it where you want in your client application. This API leverages the features of the intelligent threat JavaScript APIs to acquire and use Amazon WAF tokens after an end user successfully completes a CAPTCHA puzzle.

Implement the JavaScript integration first in a test environment, then in production. For additional coding guidance, see the sections that follow.

To use the CAPTCHA integration API

  1. Install the API

    1. Sign in to the Amazon Web Services Management Console and open the Amazon WAF console at https://console.amazonaws.cn/wafv2/.

    2. In the navigation pane, choose Application integration. On the Application integration page, you can see tabbed options.

    3. Select CAPTCHA integration.

    4. Copy the listed JavaScript integration script tag for use in your integration.

    5. In your application page code, in the <head> section, insert the script tag that you copied. This inclusion makes the CAPTCHA puzzle available for configuration and use. 

      <head>
    <script type="text/javascript" src="integrationURL/jsapi.js" defer></script>
</head>

      This <script> listing is configured with the defer attribute, but you can change the setting to async if you want a different behavior for your page.

      The CAPTCHA script also automatically loads the intelligent threat integration script if it isn't already present. The intelligent threat integration script causes your client application to automatically retrieve a token in the background on page load, and provides other token management functionality that you need for your use of the CAPTCHA API.

  2. (Optional) Add domain configuration for the client's tokens – By default, when Amazon WAF creates a token, it uses the host domain of the resource that’s associated with the web ACL. To provide additional domains for the JavaScript APIs, follow the guidance at Providing domains for use in the tokens.

  3. Get the encrypted API key for the client – The CAPTCHA API requires an encrypted API key that contains a list of valid client domains. Amazon WAF uses this key to verify that the client domain you're using with the integration is approved to use Amazon WAF CAPTCHA. To generate your API key, follow the guidance at Managing API keys for the JS CAPTCHA API.

  4. Code your CAPTCHA widget implementation – Implement the renderCaptcha() API call in your page, at the location where you want to use it. For information about configuring and using this function, see the following sections, CAPTCHA JavaScript API specification and How to render the CAPTCHA puzzle.

    The CAPTCHA implementation integrates with the intelligent threat integration APIs for token management and to run fetch calls that use the Amazon WAF tokens. For guidance about using these APIs, see Using the intelligent threat JavaScript API.

  5. Add token verification in your web ACL – Add at least one rule to your web ACL that checks for a valid CAPTCHA token in the web requests that your client sends. You can use the CAPTCHA rule action to check, as described in CAPTCHA and Challenge in Amazon WAF.

    The web ACL additions verify that requests going to your protected endpoints include the token that you've acquired in your client integration. Requests that include a valid, unexpired CAPTCHA token pass the CAPTCHA rule action inspection and do not present your end user with another CAPTCHA puzzle.

Topics