Using the intelligent threat 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 intelligent threat JavaScript API

The intelligent threat APIs provide operations for running silent challenges against the user's browser, and for handling the Amazon WAF tokens that provide proof of successful challenge and CAPTCHA responses.

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

To use the intelligent threat APIs

  1. Install the APIs

    If you use the CAPTCHA API, you can skip this step. When you install the CAPTCHA API, the script automatically installs the intelligent threat APIs.

    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 Intelligent threat integration

    4. In the tab, select the web ACL that you want to integrate with. The web ACL list includes only web ACLs that use the AWSManagedRulesACFPRuleSet managed rule group, the AWSManagedRulesATPRuleSet managed rule group, or the targeted protection level of the AWSManagedRulesBotControlRuleSet managed rule group.

    5. Open the JavaScript SDK pane, and copy the script tag for use in your integration.

    6. In your application page code, in the <head> section, insert the script tag that you copied for the web ACL. This inclusion causes your client application to automatically retrieve a token in the background on page load. 

      <head>
    <script type="text/javascript" src="Web ACL integration URL/challenge.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.

  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. Code your intelligent threat integration – Write your code to ensure that token retrieval completes before the client sends its requests to your protected endpoints. If you are already using the fetch API to make your call, you can substitute the Amazon WAF integration fetch wrapper. If you don't use the fetch API, you can use the Amazon WAF integration getToken operation instead. For coding guidance, see the following sections.

  4. Add token verification in your web ACL – Add at least one rule to your web ACL that checks for a valid challenge token in the web requests that your client sends. You can use rule groups that check and monitor challenge tokens, like the targeted level of the Bot Control managed rule group, and you can use the Challenge rule action to check, as described in CAPTCHA and Challenge in Amazon WAF.

    The web ACL additions verify that requests to your protected endpoints include the token that you've acquired in your client integration. Requests that include a valid, unexpired token pass the Challenge inspection and do not send another silent challenge to your client.

  5. (Optional) Block requests that are missing tokens – If you use the APIs with the ACFP managed rule group, the ATP managed rule group, or the targeted rules of the Bot Control rule group, these rules don't block requests that are missing tokens. To block requests that are missing tokens, follow the guidance at Blocking requests that don't have a valid Amazon WAF token.

Topics