**推出的新主控台體驗 AWS WAF** 您現在可以使用更新後的體驗，在主控台的任何位置存取 AWS WAF 功能。如需詳細資訊，請參閱[使用主控台](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html)。本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS WAF JavaScript 整合本節說明如何使用 AWS WAF JavaScript 整合。您可以使用 JavaScript 整合 APIs 在瀏覽器和其他執行 JavaScript 的裝置中實作 AWS WAF 應用程式整合。 CAPTCHA 拼圖和無提示挑戰只能在瀏覽器存取 HTTPS 端點時執行。瀏覽器用戶端必須在安全的內容中執行，才能取得字符。 + 智慧型威脅 APIs 可讓您透過無提示的用戶端瀏覽器挑戰來管理權杖授權，並在您傳送至受保護資源的請求中包含權杖。 + CAPTCHA 整合 API 會新增至智慧型威脅 APIs，並可讓您自訂用戶端應用程式中 CAPTCHA 拼圖的位置和特性。此 API 利用智慧型威脅 APIs 來取得 AWS WAF 權杖，以便在最終使用者成功完成 CAPTCHA 拼圖後，用於頁面。透過使用這些整合，您可以確保用戶端的遠端程序呼叫包含有效的字符。當您的應用程式頁面上有這些整合 APIs 時，您可以在保護套件 (Web ACL) 中實作緩解規則，例如封鎖不包含有效字符的請求。您也可以在規則中使用 Challenge或 CAPTCHA動作，實作規則來強制使用用戶端應用程式取得的字符。 **實作智慧型威脅 APIs的範例** 下列清單顯示 Web 應用程式頁面中智慧威脅 APIs典型實作的基本元件。 ``` ``` **CAPTCHA JavaScript API 的範例實作** CAPTCHA 整合 API 可讓您自訂最終使用者的 CAPTCHA 拼圖體驗。CAPTCHA 整合利用 JavaScript 智慧型威脅整合進行瀏覽器驗證和權杖管理，並新增用於設定和轉譯 CAPTCHA 拼圖的函數。下列清單顯示 CAPTCHA JavaScript API 在 Web 應用程式頁面中典型實作的基本元件。 ```

``` **Topics** + [提供用於字符的網域](waf-js-challenge-api-set-token-domain.md) + [搭配內容安全政策使用 JavaScript API](waf-javascript-api-csp.md) + [使用智慧型威脅 JavaScript API](waf-js-challenge-api.md) + [使用 CAPTCHA JavaScript API](waf-js-captcha-api.md) # 提供用於字符的網域本節說明如何提供字符的其他網域。根據預設，當 AWS WAF 建立權杖時，它會使用與保護套件 (Web ACL) 相關聯的資源的主機網域。您可以為為為 JavaScript APIs AWS WAF 建立的字符提供額外的網域。若要這樣做，`window.awsWafCookieDomainList`請使用一或多個字符網域來設定全域變數。當 AWS WAF 建立字符時，它會使用來自中網域組合中最適當、最短的網域，`window.awsWafCookieDomainList`以及與保護套件相關聯的資源主機網域 (Web ACL)。範例設定： ``` window.awsWafCookieDomainList = ['.aws.amazon.com'] ``` ``` window.awsWafCookieDomainList = ['.aws.amazon.com', 'abc.aws.amazon.com'] ``` 您無法在此清單中使用公有字尾。例如，您無法使用 `gov.au`或 `co.uk`做為清單中的字符網域。您在此清單中指定的網域必須與其他網域和網域組態相容： + 根據受保護的主機網域和為保護套件設定的字符網域清單 (Web ACL)，網域必須是 AWS WAF 將接受的網域。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。 + 如果您使用 JavaScript CAPTCHA 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 點網域的範例組態。如果您將內容安全政策 (CSP) 套用至資源，為了讓 JavaScript AWS WAF 實作運作，您需要允許列出頂點網域 `awswaf.com`。JavaScript SDKs會呼叫不同的 AWS WAF 端點，因此允許列出此網域可提供SDKs操作所需的許可。以下顯示允許列出 apex AWS WAF 網域的範例組態： ``` connect-src 'self' https://*.awswaf.com; script-src 'self' https://*.awswaf.com; script-src-elem 'self' https://*.awswaf.com; ``` 如果您嘗試將 JavaScript SDKs與使用 CSP 的資源搭配使用，而且您尚未允許列出 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 提供對使用者瀏覽器執行無提示挑戰的操作，以及處理提供成功挑戰證明和 CAPTCHA 回應的 AWS WAF 字符的操作。先在測試環境中實作 JavaScript 整合，然後在生產環境中實作。如需其他編碼指引，請參閱以下各節。 **使用智慧型威脅 APIs** 1. **安裝 APIs** 如果您使用 CAPTCHA API，則可以略過此步驟。當您安裝 CAPTCHA API 時，指令碼會自動安裝智慧型威脅 APIs。 1. 登入 AWS 管理主控台並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。 1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。在**應用程式整合**頁面上，您可以看到標籤選項。 1. 選取**智慧型威脅整合** 1. 在索引標籤中，選取您要整合的保護套件 (Web ACL)。保護套件 (Web ACL) 清單僅包含使用`AWSManagedRulesACFPRuleSet`受管規則群組、`AWSManagedRulesATPRuleSet`受管規則群組或`AWSManagedRulesBotControlRuleSet`受管規則群組的目標保護層級的保護套件 (Web ACLs)。 1. 開啟 **JavaScript SDK** 窗格，並複製指令碼標籤以用於整合。 1. 在應用程式頁面程式碼的 ``區段中，插入您為保護套件複製的指令碼標籤 (Web ACL)。此包含項目會導致您的用戶端應用程式在頁面載入的背景中自動擷取字符。 ``` ``` **在用戶端預設不連接 `aws-waf-token` Cookie 時連接字符** `AwsWafIntegration.getToken()` 會擷取有效的字符並將其儲存為 Cookie，但並非所有用戶端呼叫預設會連接此 Cookie。例如，跨主機網域進行的呼叫不會連接 Cookie。 `fetch` 包裝函式會自動處理這些案例，但如果您無法使用`fetch`包裝函式，除了從 `aws-waf-token` Cookie 讀取權杖之外，您還可以使用自訂 `x-aws-waf-token` header. AWS WAF reads 權杖來處理。下列程式碼顯示設定標頭的範例。 ``` 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-samples/aws-waf-bot-control-api-protection-with-captcha](https://github.com/aws-samples/aws-waf-bot-control-api-protection-with-captcha)。 # 使用 CAPTCHA JavaScript API 本節提供使用 CAPTCHA 整合 API 的說明。 CAPTCHA JavaScript API 可讓您設定 CAPTCHA 拼圖，並將其放置在用戶端應用程式中您想要的位置。此 API 利用智慧型威脅 JavaScript APIs的功能，在最終使用者成功完成 CAPTCHA 拼圖後取得並使用 AWS WAF 字符。先在測試環境中實作 JavaScript 整合，然後在生產環境中實作。如需其他編碼指引，請參閱以下各節。 **使用 CAPTCHA 整合 API** 1. **安裝 API** 1. 登入 AWS 管理主控台並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。 1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。在**應用程式整合**頁面上，您可以看到標籤選項。 1. 選取 **CAPTCHA 整合**。 1. 複製列出的 JavaScript 整合指令碼標籤，以用於您的整合。 1. 在應用程式頁面程式碼的 ``區段中，插入您複製的指令碼標籤。此包含項目可讓 CAPTCHA 拼圖可供組態和使用。 ``` ``` 此`

``` **範例組態設定** 下列範例清單顯示`renderCaptcha`具有寬度和標題選項非預設設定的。 ``` AwsWafCaptcha.renderCaptcha(container, { apiKey: "...API key goes here...", onSuccess: captchaExampleSuccessFunction, onError: captchaExampleErrorFunction, dynamicWidth: true, skipTitle: true }); ``` 如需組態選項的完整資訊，請參閱 [CAPTCHA JavaScript API 規格](waf-js-captcha-api-specification.md)。 # 從處理 CAPTCHA 回應 AWS WAF 本節提供處理 CAPTCHA 回應的範例。如果請求沒有具有有效 CAPTCHA 時間戳記的字符，則具有CAPTCHA動作的 AWS WAF 規則會終止對相符 Web 請求的評估。如果請求是`GET`文字/html 呼叫，則CAPTCHA動作會為用戶端提供具有 CAPTCHA 拼圖的間質。當您未整合 CAPTCHA JavaScript API 時，間質會執行拼圖，如果最終使用者成功解決，會自動重新提交請求。當您整合 CAPTCHA JavaScript API 並自訂 CAPTCHA 處理時，您需要偵測終止的 CAPTCHA 回應、提供自訂 CAPTCHA，然後如果最終使用者成功解決拼圖，請重新提交用戶端的 Web 請求。下列程式碼範例示範其做法： **注意** AWS WAF CAPTCHA 動作回應的狀態碼為 HTTP 405，用於辨識此程式碼中的CAPTCHA回應。如果您的受保護端點使用 HTTP 405 狀態碼來通訊相同呼叫的任何其他回應類型，則此範例程式碼也會轉譯這些回應的 CAPTCHA 拼圖。 ```

``` # 管理 JS CAPTCHA API 的 API 金鑰本節提供產生和刪除 API 金鑰的指示。若要將 AWS WAF CAPTCHA 與 JavaScript API 整合到用戶端應用程式，您需要要執行 CAPTCHA 拼圖之用戶端網域的 JavaScript API 整合標籤和加密的 API 金鑰。 JavaScript 的 CAPTCHA 應用程式整合 JavaScript 使用加密的 API 金鑰來驗證用戶端應用程式網域是否具有使用 AWS WAF CAPTCHA API 的許可。當您從 JavaScript 用戶端呼叫 CAPTCHA API 時，您會提供具有網域清單的 API 金鑰，其中包含目前用戶端的網域。您可以在單一加密金鑰中列出最多 5 個網域。 **API 金鑰需求** 您在 CAPTCHA 整合中使用的 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 金鑰中。目前的網域是您可以在瀏覽器地址列中看到的網域。您使用的網域必須是 AWS WAF 根據受保護的主機網域和為 Web ACL 設定的字符網域清單而接受的網域。如需詳細資訊，請參閱[AWS WAF 保護套件 (Web ACL) 權杖網域清單組態](waf-tokens-domains.md#waf-tokens-domain-lists)。 **如何選擇 API 金鑰的區域** AWS WAF 可以在可使用的任何區域中產生 CAPTCHA API AWS WAF 金鑰。一般而言，您應該使用與保護套件 (Web ACL) 相同的 CAPTCHA API 金鑰區域。不過，如果您預期全球受眾使用區域保護套件 (Web ACL)，您可以取得範圍為 CloudFront 的 CAPTCHA JavaScript 整合標籤，以及範圍為 CloudFront 的 API 金鑰，並將其與區域保護套件 (Web ACL) 搭配使用。此方法可讓用戶端從最接近它們的區域載入 CAPTCHA 拼圖，從而減少延遲。範圍限定在 CloudFront 以外區域的 CAPTCHA API 金鑰不支援跨多個區域使用。它們只能在其範圍範圍內的區域中使用。 **為您的用戶端網域產生 API 金鑰** 取得整合 URL，並透過主控台產生和擷取 API 金鑰。 1. 登入 AWS 管理主控台並在 https：//[https://console.aws.amazon.com/wafv2/homev2](https://console.aws.amazon.com/wafv2/homev2) 開啟 AWS WAF 主控台。 1. 在導覽窗格中，選擇 **Application integration (應用程式整合)**。 1. 在**已啟用應用程式整合的保護套件 (Web ACLs)** 窗格中，選取您要用於 API 金鑰的區域。您也可以在 **CAPTCHA 整合**索引標籤的 **API 金鑰**窗格中選取區域。 1. 選擇 **CAPTCHA 整合**索引標籤。此索引標籤提供 CAPTCHA JavaScript 整合標籤，您可以在整合中使用，以及 API 金鑰清單。兩者的範圍都限定為選取的區域。 1. 在 **API 金鑰**窗格中，選擇**產生金鑰**。金鑰產生對話隨即出現。 1. 輸入您要包含在金鑰中的用戶端網域。您最多可以輸入 5 個。完成後，請選擇**產生金鑰**。界面會返回列出新金鑰的 CAPTCHA 整合索引標籤。建立後，API 金鑰是不可變的。如果您需要變更金鑰，請產生新的金鑰並改用該金鑰。 1. （選用）複製新產生的金鑰以用於整合。您也可以為此工作使用 REST APIs 或其中一種特定語言 AWS SDKs。REST API 呼叫是 [CreateAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_CreateAPIKey.html) 和 [ListAPIKeys](https://docs.aws.amazon.com/waf/latest/APIReference/API_ListAPIKeys.html)。 **刪除 API 金鑰** 若要刪除 API 金鑰，您必須使用 REST API 或其中一種語言 AWS SDKs。REST API 呼叫是 [DeleteAPIKey](https://docs.aws.amazon.com/waf/latest/APIReference/API_DeleteAPIKey.html)。您無法使用主控台刪除金鑰。刪除金鑰後，最多可能需要 24 小時 AWS WAF 才能禁止在所有區域中使用金鑰。