使用通用金鑰設定政策引擎

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本文說明如何使用通用金鑰，在網站上設定 Policy Engine。通用金鑰是全新的 Google Cloud Fraud Defense 金鑰，支援在政策引擎中建立規則。

Fraud Defense 可透過政策引擎，根據您設定的自訂政策規則，觸發 CAPTCHA 驗證問題。這些規則可能會根據風險分數、IP 位址、使用者代理程式、ASN 或經過驗證的機器人 (AI 代理程式) 身分，決定何時顯示 Fraud Defense 驗證。

Fraud Defense 政策引擎設定提供兩項主要功能：

• AutoExecute 整合 (protected_endpoint_group)：自動檢查傳出的非同步網路要求，並將 reCAPTCHA 權杖附加至要求，簡化前端 JavaScript 整合作業，因此前端只需要指令碼標記。
• 挑戰政策 (challenge_rule_groups)：決定是否在不同使用者動作中顯示挑戰，並使用自訂 CEL 規則設定相關挑戰難度等級 (USABILITY、BALANCE、SECURITY)。

事前準備

1. 準備 reCAPTCHA 環境。

2. 確認專案已啟用計費功能 Google Cloud 。

   如要使用政策引擎，專案必須連結並啟用計費功能，才能使用 Fraud Defense。你可以使用信用卡或現有的 Google Cloud 專案帳單 ID 啟用帳單。如需帳單方面的協助，請與 Cloud Billing 支援團隊聯絡。

建立通用金鑰

請根據偏好的介面，選擇適當的選項來建立通用金鑰：

控制台

1. 前往 Google Cloud 控制台的「reCAPTCHA」reCAPTCHA頁面。

   前往 reCAPTCHA

2. 確認頁面頂端的資源選取器中顯示專案名稱。

   如果沒有看到專案名稱，請按一下資源選取器，然後選取專案。

3. 選取「金鑰」分頁標籤。
4. 按一下「建立金鑰」。
5. 在「顯示名稱」欄位中，輸入金鑰的顯示名稱。
6. 在「應用程式類型」部分，選取「通用」。
7. 按一下 [Create key] (建立金鑰)。

新建立的金鑰會列在「reCAPTCHA 金鑰」頁面。

gcloud

如要使用 Google Cloud CLI 建立通用金鑰，請使用 --universal 旗標執行 gcloud recaptcha keys create 指令：

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

回應包含新建立的 reCAPTCHA Universal 金鑰。

REST API

如要使用 REST API 建立通用金鑰，請使用 projects.keys.create 方法並指定 universalSettings：

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

更改下列內容：

• PROJECT_ID：您的 Google Cloud 專案 ID
• DISPLAY_NAME：金鑰的顯示名稱，通常是您的網站名稱

回應包含新建立的 reCAPTCHA Universal 金鑰。

設定 Policy Engine 的網域

注意： 如果是網站，reCAPTCHA 金鑰是您指定網域和子網域專屬的金鑰。如果您從多個網域提供網站服務，可以指定多個網域。如果您指定網域 (例如 examplepetstore.com)，就不必指定子網域 (例如 subdomain.examplepetstore.com)。

根據偏好的介面，選擇適當的選項，為通用金鑰設定允許的網域：

控制台

1. 前往 Google Cloud 控制台的「Fraud Defense」(詐欺防禦) 頁面。

   前往 Fraud Defense

2. 確認頁面頂端的資源選取器中顯示了專案名稱。

   如果沒有看到專案名稱，請按一下資源選取器，然後選取專案。

3. 按一下「reCAPTCHA 金鑰」分頁標籤。

4. 找出要設定的通用金鑰，然後按一下該金鑰。

5. 在「金鑰詳細資料」頁面中，按一下「編輯金鑰」。

6. 找出「金鑰用途設定」部分。

   如要保護網域和子網域的 reCAPTCHA 金鑰，請務必關閉「停用網域驗證」切換鈕。

   停用網域驗證功能會造成安全風險，因為網站沒有任何限制，任何人都能存取及使用 reCAPTCHA 金鑰。

   輸入網站的網域名稱：

   1. 在「網域清單」部分，按一下「新增網域」。
   2. 在「網域」欄位中，輸入網域名稱。
   3. 選用：如要新增其他網域，請按一下「新增網域」，然後在「網域」欄位中輸入其他網域名稱。您最多可以新增 250 個網域。

7. 按一下 [儲存變更]。

注意： 如要在超過 250 個網域上使用政策，請點選「停用網域驗證」切換鈕。停用網域驗證後，Fraud Defense 會忽略網域清單，您必須自行檢查所建立評估作業中的「tokenProperties.hostname」欄位，執行網域驗證。

gcloud

如要使用 Google Cloud CLI 更新通用金鑰的允許網域，請使用 gcloud alpha recaptcha policies update 指令，並在政策設定檔中指定網域 (例如 POLICY.yaml)：

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

注意： gcloud alpha recaptcha policies update 指令會更新整個政策。如要避免刪除現有的 protected_endpoint_group 或 challenge_rule_groups，請務必將這些項目納入 POLICY.yaml 檔案。

POLICY.yaml 檔案必須在 clientSettings 下指定允許的網域：

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

或者，如要允許所有網域並停用網域驗證，請在 POLICY.yaml 檔案中將 allowAllDomains 設為 true：

clientSettings:
  allowAllDomains: true

更改下列內容：

• KEY_ID：通用金鑰的 ID 或完整資源名稱
• DOMAIN_NAME_1、DOMAIN_NAME_2：允許使用金鑰的網站網域名稱

注意： 當 allowAllDomains 設為 true 時，詐欺防禦機制會忽略網域清單，您必須自行檢查所建立評估中的 tokenProperties.hostname 欄位，以驗證網域。

REST API

如要使用 REST API 更新通用金鑰的允許網域，請使用 projects.keys.updatePolicy 方法。

使用任何要求資料之前，請先修改下列項目的值：

• PROJECT_ID：您的 Google Cloud 專案 ID
• KEY_ID：通用金鑰的 ID
• DOMAIN_NAME_1、DOMAIN_NAME_2：允許使用金鑰的網站網域名稱

HTTP 方法和網址：

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

JSON 要求主體：

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

如果要求成功，系統會傳回更新後的政策設定。

注意： 如要在超過 250 個網域上使用政策，請在要求主體中將 allowAllDomains 設為 true。如果 allowAllDomains 設為 true，Fraud Defense 會忽略網域清單，您必須自行檢查所建立評估作業中的 tokenProperties.hostname 欄位，執行網域驗證。

後續步驟

• 在網頁中安裝通用金鑰。