**引入全新的主机体验 AWS WAF** 现在，您可以使用更新的体验访问控制台中任意位置的 AWS WAF 功能。有关更多详细信息，请参阅[使用控制台](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)。本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS WAF JavaScript 集成本节介绍如何使用集 AWS WAF JavaScript 成。您可以使用该 JavaScript 集成 APIs 在浏览器和其他执行设备中实现 AWS WAF 应用程序集成。 JavaScript 只有当浏览器访问 HTTPS 端点时，才能运行验证码拼图和静默质询。浏览器客户端必须在安全环境中运行才能获取令牌。 + 智能威胁 APIs 允许您通过静默的客户端浏览器挑战来管理令牌授权，并在发送到受保护资源的请求中包含令牌。 + CAPTCHA 集成 API 增加了智能威胁 APIs，允许您自定义验证码拼图在客户端应用程序中的位置和特征。在最终用户成功完成验证码拼图后，此 API 利用智能威胁获取 AWS WAF 令牌 APIs 以在页面中使用。通过使用这些集成，可以确保客户端的远程过程调用包含有效的令牌。在应用程序页面上进行 APIs 这些集成后，您可以在保护包 (Web ACL) 中实施缓解规则，例如阻止不包含有效令牌的请求。您还可以通过在规则中使用 Challenge 或 CAPTCHA 操作来实施强制使用客户端应用程序获取的令牌的规则。 **智能威胁的实施示例 APIs** 以下列表显示了 Web 应用程序页面 APIs 中智能威胁的典型实现的基本组件。 ``` ``` **验证码 AP JavaScript I 的实现示例** 验证码集成 API 可让您自定义最终用户的验证码拼图体验。CAPTCHA 集成利用 JavaScript 智能威胁集成进行浏览器验证和令牌管理，并添加了配置和呈现 CAPTCHA 拼图的功能。以下列表显示了 Web 应用程序页面中典型的 CAPTCHA JavaScript API 实现的基本组件。 ```

``` **Topics** + [提供用于令牌的域名](waf-js-challenge-api-set-token-domain.md) + [将 JavaScript API 与内容安全策略配合使用](waf-javascript-api-csp.md) + [使用智能威胁 JavaScript API](waf-js-challenge-api.md) + [使用验证码 API JavaScript](waf-js-captcha-api.md) # 提供用于令牌的域名本节介绍了如何为令牌提供其他域。默认情况下，在 AWS WAF 创建令牌时，它使用与保护包关联的资源的主机域 (Web ACL)。您可以为为 AWS WAF 创建的令牌提供其他域名 JavaScript APIs。为此，请使用一个或多个令牌域配置全局变量 `window.awsWafCookieDomainList`。 AWS WAF 创建令牌时，它会使用与保护包 (Web ACL) 关联的资源的域`window.awsWafCookieDomainList`和主机域组合中最合适、最短的域。设置示例： ``` window.awsWafCookieDomainList = ['.aws.amazon.com'] ``` ``` window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com'] ``` 您不能在此列表中使用公共后缀。例如，您不能在列表中使用 `gov.au` 或 `co.uk` 作为令牌域。您在此列表中指定的域名必须与您的其他域名和域名配置兼容： + 根据受保护的主机域和 AWS WAF 为保护包配置的令牌域列表（Web ACL），这些域必须是可以接受的域。有关更多信息，请参阅 [AWS WAF 保护包 (Web ACL) 令牌域列表配置](waf-tokens-domains.md#waf-tokens-domain-lists)。 + 如果您使用 CAP JavaScript TCHA API，则您的 CAPTCHA API 密钥中至少有一个域名必须与中的一个令牌域名完全匹配，`window.awsWafCookieDomainList`或者该域名必须是其中一个令牌域的顶点域。例如，对于令牌域 `mySubdomain.myApex.com`，API 密钥 `mySubdomain.myApex.com` 完全匹配，API 密钥 `myApex.com` 是顶点域。任一密钥都与令牌域相匹配。有关 API 密钥的更多信息，请参阅 [管理 JS CAPTCHA API 的 API 密钥](waf-js-captcha-api-key.md)。如果您使用 `AWSManagedRulesACFPRuleSet` 托管规则组，则可以配置一个与您在规则组配置中提供的账户创建路径中的域名相匹配的域。有关此配置的更多信息，请参阅[将 ACFP 托管规则组添加到您的 web ACL](waf-acfp-rg-using.md)。如果您使用 `AWSManagedRulesATPRuleSet` 托管规则组，则可以配置一个与您在规则组配置中提供的登录路径中的域名相匹配的域。有关此配置的更多信息，请参阅[将 ATP 托管规则组添加到您的保护包（web ACL）](waf-atp-rg-using.md)。 # 将 JavaScript API 与内容安全策略配合使用本节提供了将 AWS WAF apex 域列入许可名单的配置示例。如果您将内容安全策略 (CSP) 应用于您的资源，则需要将 AWS WAF apex 域列入许可名单，才能使您的 JavaScript实施发挥作用。`awswaf.com`它们 JavaScript SDKs 会调用不同的 AWS WAF 端点，因此将此域列入许可名单可提供操作 SDKs 所需的权限。以下显示了将 AWS WAF apex 域列入许可名单的配置示例： ``` connect-src 'self' https://*.awswaf.com; script-src 'self' https://*.awswaf.com; script-src-elem 'self' https://*.awswaf.com; ``` 如果您尝试与使用 CSP 的资源 JavaScript SDKs 一起使用，但您尚未将该 AWS WAF 域列入许可名单，则会收到如下错误： ``` Refused to load the script ...awswaf.com/<> because it violates the following Content Security Policy directive: “script-src ‘self’ ``` # 使用智能威胁 JavaScript API 本节提供在客户端应用程序中使用智能威胁 JavaScript API 的说明。智能威胁 APIs 提供了针对用户的浏览器运行静默挑战的操作，以及处理提供成功挑战和验证码响应证明的 AWS WAF 令牌的操作。首先在测试环境中实施 JavaScript 集成，然后在生产环境中实现集成。有关其他编码指导，请参阅以下各节。 **使用智能威胁 APIs** 1. **安装 APIs** 如果您使用验证码 API，可以跳过此步骤。当你安装 CAPTCHA API 时，脚本会自动安装智能威胁。 APIs 1. 登录 AWS 管理控制台并在 [https://console.aws.amazon.com/wafv2/homev](https://console.aws.amazon.com/wafv2/homev2) 2 上打开主 AWS WAF 机。 1. 在导航窗格中，选择 **应用程序集成**。在**应用程序集成**页面上，您可以看到选项卡式选项。 1. 选择**智能威胁集成** 1. 在该选项卡中，选择要与之集成的保护包（web ACL）。保护包 (Web ACL) 列表仅包括使用`AWSManagedRulesACFPRuleSet`托管规则组、托管规则组或`AWSManagedRulesATPRuleSet`托管规则组的目标保护级别的保护包 (Web ACLs)。`AWSManagedRulesBotControlRuleSet` 1. 打开 S **JavaScript DK** 窗格，复制脚本标签以便在集成中使用。 1. 在应用程序页面代码的 `` 部分中，插入您为保护包（web ACL）复制的脚本标记。此包含会使您的客户端应用程序在页面加载时自动在后台检索令牌。 ``` ``` **当客户端默认不附加 `aws-waf-token` Cookie 时附加令牌** `AwsWafIntegration.getToken()` 检索有效令牌并将其存储为 Cookie，但并非所有客户端调用都默认附加此 Cookie。例如，跨主机域发出的调用不会附加 Cookie。 `fetch`包装器会自动处理这些情况，但是如果您无法使用`fetch`包装器，则可以使用自定义`x-aws-waf-token`标题来处理此问题。 AWS WAF 除了从 `aws-waf-token` Cookie 中读取令牌外，还会从该标头中读取令牌。以下代码显示了设置标头的示例： ``` const token = await AwsWafIntegration.getToken(); const result = await fetch('/url', { headers: { 'x-aws-waf-token': token, }, }); ``` 默认情况下， AWS WAF 仅接受包含与请求的主机域相同域名的令牌。任何跨域令牌都需要在保护包（web ACL）令牌域列表中有相应条目。有关更多信息，请参阅 [AWS WAF 保护包 (Web ACL) 令牌域列表配置](waf-tokens-domains.md#waf-tokens-domain-lists)。有关跨域令牌使用的更多信息，请参阅 [aws-s aws-waf-bot-control](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha) amples/-。api-protection-with-captcha # 使用验证码 API JavaScript 本节提供了使用 CAPTCHA 集成 API 的说明。 CAPTCHA JavaScript API 允许您配置验证码拼图并将其放置在客户端应用程序中所需的位置。在最终用户成功完成验证码拼图后 JavaScript APIs ，此 API 利用智能威胁的功能来获取和使用 AWS WAF 代币。首先在测试环境中实施 JavaScript 集成，然后在生产环境中实现集成。有关其他编码指导，请参阅以下各节。 **使用验证码集成 API** 1. **安装 API** 1. 登录 AWS 管理控制台并在 [https://console.aws.amazon.com/wafv2/homev](https://console.aws.amazon.com/wafv2/homev2) 2 上打开主 AWS WAF 机。 1. 在导航窗格中，选择 **应用程序集成**。在**应用程序集成**页面上，您可以看到选项卡式选项。 1. 选择**验证码集成**。 1. 复制列出的 JavaScript 集成脚本标签，以便在集成中使用。 1. 在应用程序页面代码的 `` 部分中，插入您复制的脚本标签。此功能使验证码拼图可供配置和使用。 ``` ``` 此 `

``` **配置设置示例** 以下示例列表显示了宽度和标题选项的非默认设置 `renderCaptcha`。 ``` AwsWafCaptcha.renderCaptcha(container, { apiKey: "...API key goes here...", onSuccess: captchaExampleSuccessFunction, onError: captchaExampleErrorFunction, dynamicWidth: true, skipTitle: true }); ``` 有关配置选项的全部信息，请参阅 [验证码 API 规范 JavaScript](waf-js-captcha-api-specification.md)。 # 处理来自的验证码响应 AWS WAF 本节提供了处理验证码响应的示例。如果匹配的 Web 请求没有带有有效 CAPTCHA 时间戳的令牌，则带有CAPTCHA操作的 AWS WAF 规则将终止对该请求的评估。如果请求是`GET` text/html 通话，则该CAPTCHA操作会向客户提供带有验证码拼图的插页式广告。当你不集成 CAPTCHA JavaScript API 时，插页式广告会运行拼图，如果最终用户成功解决了这个问题，则会自动重新提交请求。当你集成 CAPTCHA JavaScript API 并自定义验证码处理时，你需要检测终止的验证码响应，提供你的自定义 CAPTCHA，然后如果最终用户成功解决了难题，则重新提交客户的 Web 请求。以下代码示例演示如何执行此操作。 **注意** AWS WAF CAPTCHA操作响应的状态码为 HTTP 405，我们用它来识别此代码中的CAPTCHA响应。如果您的受保护端点使用 HTTP 405 状态代码为同一调用传递任何其他类型的响应，本示例代码也会为这些响应显示验证码拼图。 ```

``` # 管理 JS CAPTCHA API 的 API 密钥本节提供了生成和删除 API 密钥的说明。要将 AWS WAF 验证码集成到带有 JavaScript API 的客户端应用程序中，您需要用于运行验证码拼图的客户端域的 API 集成标签和加密 API 密钥。 JavaScript 的 CAPTCHA 应用程序集成 JavaScript 使用加密的 API 密钥来验证客户端应用程序域是否有权使用 AWS WAF CAPTCHA API。当您从 JavaScript 客户端调用 CAPTCHA API 时，您需要提供一个 API 密钥和一个包含当前客户端域名的域名列表。一个加密密钥最多可列出 5 个域。 **API 密钥要求** 您在验证码集成中使用的 API 密钥必须包含一个适用于您使用密钥的客户端的域。 + 如果您在客户的智能威胁集成中指定了 `window.awsWafCookieDomainList`，那么您的 API 密钥中至少有一个域必须与 `window.awsWafCookieDomainList` 中的一个令牌域完全匹配，或者必须是其中一个令牌域的顶点域。例如，对于令牌域 `mySubdomain.myApex.com`，API 密钥 `mySubdomain.myApex.com` 完全匹配，API 密钥 `myApex.com` 是顶点域。任一密钥都与令牌域相匹配。有关设置令牌域列表的信息，请参阅 [提供用于令牌的域名](waf-js-challenge-api-set-token-domain.md)。 + 否则，当前域名必须包含在 API 密钥中。当前域名是您可以在浏览器地址栏中看到的域名。根据受保护的主机域和为 Web ACL 配置的令牌域列表，您使用的域必须是可以接受的域。 AWS WAF 有关更多信息，请参阅 [AWS WAF 保护包 (Web ACL) 令牌域列表配置](waf-tokens-domains.md#waf-tokens-domain-lists)。 **如何为 API 密钥选择区域** AWS WAF 可以在任何可用的区域生成 CAPTCHA API 密钥。 AWS WAF 通常，您应为 CAPTCHA API 密钥使用与保护包（web ACL）相同的区域。但是，如果您希望全球受众使用区域保护包（Web ACL），则可以获取范围为的验证码 JavaScript 集成标签 CloudFront 和范围为的API密钥，然后将其与区域保护包（Web ACL）一起使用。 CloudFront这种方法允许客户端从距其最近的区域加载验证码拼图，从而减小延迟。 CAPTCHA API 密钥的作用域仅限于其他区域 CloudFront ，不支持跨多个区域使用。它们只能在适用范围内的区域中使用。 **为您的客户端域生成 API 密钥** 通过控制台获取集成 URL 并生成和检索 API 密钥。 1. 登录 AWS 管理控制台并在 [https://console.aws.amazon.com/wafv2/homev](https://console.aws.amazon.com/wafv2/homev2) 2 上打开主 AWS WAF 机。 1. 在导航窗格中，选择 **应用程序集成**。 1. 在**为应用程序集成启用的保护包 (Web ACLs)** 窗格中，选择要用于 API 密钥的区域。您还可以在 **CAPTCHA 集成**选项卡的 **API 密钥**窗格中选择区域。 1. 选择**验证码集成**选项卡。此选项卡提供可在 JavaScript 集成中使用的 CAPTCHA 集成标签以及 API 密钥列表。两者的范围均限于所选区域。 1. 在 **API 密钥**窗格中，选择**生成密钥**。此时将显示生成密钥对话框。 1. 输入要包含在密钥中的客户端域。您最多可以输入 5 个。完成后，选择**生成密钥**。界面返回到验证码集成选项卡，其中列出了您的新密钥。 API 密钥一经创建，即不可变。如果您需要更改密钥，请生成一个新密钥并改用该密钥。 1. （可选）复制新生成的密钥以用于集成。您也可以使用 REST APIs 或特定语言之一来完成这项 AWS SDKs 工作。REST API 调用是 “[创建” APIKey 和 “](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html)[列出” APIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html)。 **删除 API 密钥** 要删除 API 密钥，必须使用 REST API 或特定语言之一 AWS SDKs。REST API 调用为[删除APIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html)。您不能使用控制台删除键。删除密钥后，最长可能需要 24 小时 AWS WAF 才能禁止在所有地区使用该密钥。