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

預覽

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

本文說明如何使用通用金鑰，在網站上設定政策引擎。通用金鑰是新的 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. 準備 Google Cloud Fraud Defense 環境。

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

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

建立通用金鑰

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

控制台

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

   前往 Google Cloud Fraud Defense

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

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

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

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

gcloud

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

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

回應中會包含新建立的通用金鑰。

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 金鑰是您指定的網域和子網域專屬。如果網站透過多個網域提供服務，您可以指定多個網域。如果指定網域 (例如 examplepetstore.com)，就不必指定子網域 (例如 subdomain.examplepetstore.com)。

視您偏好的介面而定，請選擇適當的選項，為通用金鑰設定允許的網域：

控制台

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

   前往 Fraud Defense

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

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

3. 按一下「Keys」(金鑰) 分頁標籤。

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

5. 在「Key details」(金鑰詳細資料) 頁面中，按一下「Edit key」(編輯金鑰)。

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

   為保護網域和子網域的 reCAPTCHA 金鑰，請務必關閉「Disable domain verification」(停用網域驗證) 切換鈕。

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

   輸入網站的網域名稱：

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

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

注意： 如要在超過 250 個網域上使用政策，請按一下「Disable domain verification」(停用網域驗證) 切換鈕。停用網域驗證後，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 指令會更新整個政策。POLICY.yaml 檔案必須包含任何現有的 protected_endpoint_group 或 challenge_rule_groups，以免遭到刪除。

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，Fraud Defense 會忽略網域清單，您必須自行驗證網域，方法是檢查所建立評估作業中的 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 欄位。

後續步驟

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