**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). # AWS WAF JavaScript integrations This section explains how to use the AWS WAF JavaScript integrations. You can use the JavaScript integration APIs to implement AWS WAF application integrations in your browsers and other devices that execute JavaScript. 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. + The intelligent threat APIs let you manage token authorization through a silent client-side browser challenge, and to include the tokens in the requests that you send to your protected resources. + The CAPTCHA integration API adds to the intelligent threat APIs, and lets you customize the placement and characteristics of the CAPTCHA puzzle in your client applications. This API leverages the intelligent threat APIs to acquire AWS WAF tokens for use in the page after the end user successfully completes the CAPTCHA puzzle. By using these integrations, you ensure that the remote procedure calls by your client contain a valid token. When these integration APIs are in place on your application's pages, you can implement mitigating rules in your protection pack (web ACL), such as blocking requests that don't contain a valid token. You can also implement rules that enforce the use of the tokens that your client applications obtain, by using the Challenge or CAPTCHA actions in your rules. **Example implementation of intelligent threat APIs** The following listing shows basic components of a typical implementation of the intelligent threat APIs in a web application page. ``` ``` **Example implementation of CAPTCHA JavaScript API** The CAPTCHA integration API lets you customize your end users' CAPTCHA puzzle experience. The CAPTCHA integration leverages the JavaScript intelligent threat integration, for browser verification and token management, and adds a function for configuring and rendering the CAPTCHA puzzle. The following listing shows basic components of a typical implementation of the CAPTCHA JavaScript API in a web application page. ```

``` **Topics** + [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md) + [Using the JavaScript API with content security policies](waf-javascript-api-csp.md) + [Using the intelligent threat JavaScript API](waf-js-challenge-api.md) + [Using the CAPTCHA JavaScript API](waf-js-captcha-api.md) # Providing domains for use in the tokens This section explains how to provide additional domains for tokens. By default, when AWS WAF creates a token, it uses the host domain of the resource that’s associated with the protection pack (web ACL). You can provide additional domains for the tokens that AWS WAF creates for the JavaScript APIs. To do this, configure the global variable `window.awsWafCookieDomainList`, with one or more token domains. When AWS WAF creates a token, it uses the most appropriate, shortest domain from among the combination of the domains in `window.awsWafCookieDomainList` and the host domain of the resource that’s associated with the protection pack (web ACL). Example settings: ``` window.awsWafCookieDomainList = ['.aws.amazon.com'] ``` ``` window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com'] ``` You can't use public suffixes in this list. For example, you can't use `gov.au` or `co.uk` as token domains in the list. The domains that you specify in this list must be compatible with your other domains and domain configurations: + The domains must be ones that AWS WAF will accept, based on the protected host domain and the token domain list that's configured for the protection pack (web ACL). For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists). + If you use the JavaScript CAPTCHA API, at least one domain in your CAPTCHA API key must be an exact match for one of the token domains in `window.awsWafCookieDomainList` or it must be the apex domain of one of those token domains. For example, for the token domain `mySubdomain.myApex.com`, the API key `mySubdomain.myApex.com` is an exact match and the API key `myApex.com` is the apex domain. Either key matches the token domain. For more information about the API keys, see [Managing API keys for the JS CAPTCHA API](waf-js-captcha-api-key.md). If you use the `AWSManagedRulesACFPRuleSet` managed rule group, you might configure a domain that matches the one in the account creation path that you provided to the rule group configuration. For more information about this configuration, see [Adding the ACFP managed rule group to your web ACL](waf-acfp-rg-using.md). If you use the `AWSManagedRulesATPRuleSet` managed rule group, you might configure a domain that matches the one in the login path that you provided to the rule group configuration. For more information about this configuration, see [Adding the ATP managed rule group to your protection pack (web ACL)](waf-atp-rg-using.md). # Using the JavaScript API with content security policies This section provides an example configuration to allowlist the AWS WAF apex domain. If you apply content security policies (CSP) to your resources, for your JavaScript implementation to work, you need to allowlist the AWS WAF apex domain `awswaf.com`. The JavaScript SDKs make calls to different AWS WAF endpoints, so allowlisting this domain provides the permissions that the SDKs need to operate. The following shows an example configuration to allowlist the AWS WAF apex domain: ``` connect-src 'self' https://*.awswaf.com; script-src 'self' https://*.awswaf.com; script-src-elem 'self' https://*.awswaf.com; ``` If you try to use the JavaScript SDKs with resources that use CSP, and you haven't allowlisted the AWS WAF domain, you'll receive errors like the following: ``` Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’ ``` # 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 AWS 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 AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 1. In the navigation pane, choose **Application integration**. On the **Application integration** page, you can see tabbed options. 1. Select **Intelligent threat integration** 1. In the tab, select the protection pack (web ACL) that you want to integrate with. The protection pack (web ACL) list includes only protection packs (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. 1. Open the **JavaScript SDK** pane, and copy the script tag for use in your integration. 1. In your application page code, in the `` section, insert the script tag that you copied for the protection pack (web ACL). This inclusion causes your client application to automatically retrieve a token in the background on page load. ``` ``` **Attaching the token when your client doesn't attach the `aws-waf-token` cookie by default** `AwsWafIntegration.getToken()` retrieves a valid token and stores it as a cookie, but not all client calls attach this cookie by default. For example, calls made across host domains don't attach the cookie. The `fetch` wrapper handles these cases automatically, but if you aren't able to use the `fetch` wrapper, you can handle this by using a custom `x-aws-waf-token` header. AWS WAF reads tokens from this header, in addition to reading them from the `aws-waf-token` cookie. The following code shows an example of setting the header. ``` const token = await AwsWafIntegration.getToken(); const result = await fetch('/url', { headers: { 'x-aws-waf-token': token, }, }); ``` By default, AWS WAF only accepts tokens that contain the same domain as the requested host domain. Any cross-domain tokens require corresponding entries in the protection pack (web ACL) token domain list. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists). For additional information about cross-domain token use, see [aws-samples/aws-waf-bot-control-api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha). # Using the CAPTCHA JavaScript API This section provides instructions for using the CAPTCHA integration 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 AWS 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 AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 1. In the navigation pane, choose **Application integration**. On the **Application integration** page, you can see tabbed options. 1. Select **CAPTCHA integration**. 1. Copy the listed JavaScript integration script tag for use in your integration. 1. In your application page code, in the `` section, insert the script tag that you copied. This inclusion makes the CAPTCHA puzzle available for configuration and use. ``` ``` This `

``` **Example configuration settings** The following example listing shows the `renderCaptcha` with non-default settings for the width and the title options. ``` AwsWafCaptcha.renderCaptcha(container, { apiKey: "...API key goes here...", onSuccess: captchaExampleSuccessFunction, onError: captchaExampleErrorFunction, dynamicWidth: true, skipTitle: true }); ``` For full information about the configuration options, see [CAPTCHA JavaScript API specification](waf-js-captcha-api-specification.md). # Handling a CAPTCHA response from AWS WAF This section provides an example of handling a CAPTCHA response. An AWS WAF rule with a CAPTCHA action terminates the evaluation of a matching web request if the request doesn't have a token with a valid CAPTCHA timestamp. If the request is a `GET` text/html call, the CAPTCHA action then serves the client an interstitial with a CAPTCHA puzzle. When you don't integrate the CAPTCHA JavaScript API, the interstitial runs the puzzle and, if the end user successfully solves it, automatically resubmits the request. When you integrate the CAPTCHA JavaScript API and customize your CAPTCHA handling, you need to detect the terminating CAPTCHA response, serve your custom CAPTCHA, and then if the end user successfully solves the puzzle, resubmit the client's web request. The following code example shows how to do this. **Note** The AWS WAF CAPTCHA action response has a status code of HTTP 405, which we use to recognize the CAPTCHA response in this code. If your protected endpoint uses an HTTP 405 status code to communicate any other type of response for the same call, this example code will render a CAPTCHA puzzle for those responses as well. ```

``` # Managing API keys for the JS CAPTCHA API This section provides instructions for generating and deleting API keys. To integrate AWS WAF CAPTCHA into a a client application with the JavaScript API, you need the JavaScript API integration tag and the encrypted API key for the client domain where you want to run your CAPTCHA puzzle. The CAPTCHA application integration for JavaScript uses the encrypted API keys to verify that the client application domain has permission to use the AWS WAF CAPTCHA API. When you call the CAPTCHA API from your JavaScript client, you provide an API key with a domain list that includes a domain for the current client. You can list up to 5 domains in a single encrypted key. **API key requirements** The API key that you use in your CAPTCHA integration must contain a domain that applies to the client where you use the key. + If you specify a `window.awsWafCookieDomainList` in your client's intelligent threat integration, then at least one domain in your API key must be an exact match for one of the token domains in `window.awsWafCookieDomainList` or it must be the apex domain of one of those token domains. For example, for the token domain `mySubdomain.myApex.com`, the API key `mySubdomain.myApex.com` is an exact match and the API key `myApex.com` is the apex domain. Either key matches the token domain. For information about the setting the token domain list, see [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md). + Otherwise, the current domain must be contained in the API key. The current domain is the domain that you can see in the browser address bar. The domains that you use must be ones that AWS WAF will accept, based on the protected host domain and the token domain list that's configured for the web ACL. For more information, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists). **How to choose the Region for your API key** AWS WAF can generate CAPTCHA API keys in any Region where AWS WAF is available. As a general rule, you should use the same Region for your CAPTCHA API key as you use for your protection pack (web ACL). If you expect a global audience for a regional protection pack (web ACL), however, you can obtain a CAPTCHA JavaScript integration tag that's scoped to CloudFront and an API key that's scoped to CloudFront, and use them with a regional protection pack (web ACL). This approach allows clients to load a CAPTCHA puzzle from the Region that's closest to them, which reduces latency. CAPTCHA API keys that are scoped to Regions other than CloudFront are not supported for use across multiple Regions. They can only be used in the Region they are scoped to. **To generate an API key for your client domains** To obtain the integration URL and generate and retrieve the API keys through the console. 1. Sign in to the AWS Management Console and open the AWS WAF console at [https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2). 1. In the navigation pane, choose **Application integration**. 1. In the pane, **protection packs (web ACLs) that are enabled for application integration**, select the Region that you want to use for your API key. You can also select the Region in the **API keys** pane of the **CAPTCHA integration** tab. 1. Choose the tab **CAPTCHA integration**. This tab provides the CAPTCHA JavaScript integration tag, which you can use in your integration, and the API keys listing. Both are scoped to the selected Region. 1. In the **API keys** pane, choose **Generate key**. The key generation dialogue appears. 1. Enter the client domains that you want to include in the key. You can enter up to 5. When you're finished, choose **Generate key**. The interface returns to the CAPTCHA integration tab, where your new key is listed. Once created, an API key is immutable. If you need to make changes to a key, generate a new key and use that instead. 1. (Optional) Copy the newly generated key for use in your integration. You can also use the REST APIs or one of the language-specific AWS SDKs for this work. The REST API calls are [CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) and [ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html). **To delete an API key** To delete an API key, you must use the REST API or one of the language specific AWS SDKs. The REST API call is [DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html). You can't use the console to delete a key. After you delete a key, it can take up to 24 hours for AWS WAF to disallow use of the key in all regions.