Using the intelligent threat JavaScript API
This section provides instructions for using the intelligent threat JavaScript API in your client application.
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
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.
Sign in to the Amazon Web Services Management Console and open the Amazon WAF console at https://console.amazonaws.cn/wafv2/
. -
In the navigation pane, choose Application integration. On the Application integration page, you can see tabbed options.
Select Intelligent threat integration
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, theAWSManagedRulesATPRuleSet
managed rule group, or the targeted protection level of theAWSManagedRulesBotControlRuleSet
managed rule group.Open the JavaScript SDK pane, and copy the script tag for use in your integration.
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 thedefer
attribute, but you can change the setting toasync
if you want a different behavior for your page.
-
(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.
-
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 integrationfetch
wrapper. If you don't use thefetch
API, you can use the Amazon WAF integrationgetToken
operation instead. For coding guidance, see the following sections. -
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.
-
(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.