為網站建立 reCAPTCHA 金鑰

您可以建立 reCAPTCHA 金鑰，驗證網頁上的使用者互動。

reCAPTCHA 金鑰代表網站的 reCAPTCHA 設定方式。設定包含重要選項，例如是否顯示 CAPTCHA 驗證問題。

事前準備

• 準備 Google Cloud Fraud Defense 環境。
• 確認您具備下列 Identity and Access Management 角色：reCAPTCHA Enterprise 管理員 (roles/recaptchaenterprise.admin)。
• 選擇最適合您用途的金鑰類型。

建立 reCAPTCHA 金鑰

您可以為 Google Cloud 專案建立的 reCAPTCHA 金鑰數量沒有上限。建議您為每個網站建立一個 reCAPTCHA 金鑰。

建議您為測試和正式環境建立不同的 reCAPTCHA 金鑰。否則，測試環境中的資料可能會影響 reCAPTCHA 風險分析。

Cloud 控制台

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

   前往 Google Cloud Fraud Defense

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

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

3. 選取「金鑰」分頁標籤。
4. 按一下「建立金鑰」。
5. 在「Display name」(顯示名稱) 欄位中，輸入金鑰的顯示名稱。
6. 在「Application type」部分，選取「Web」。

   「網域清單」部分隨即顯示。

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

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

8. 輸入網站的網域名稱：

   1. 在「網域清單」部分，按一下「新增網域」。
   2. 在「Domain」欄位中輸入網域名稱。

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

      如果是網站，reCAPTCHA 金鑰會因您指定的網域和子網域而異。如果網站透過多個網域提供服務，您可以指定多個網域。如果您指定網域 (例如 examplepetstore.com)，就不需要指定其子網域 (例如 subdomain.examplepetstore.com)。網域清單變更最多可能需要 30 分鐘才會生效。

      如要在超過 250 個網域上使用金鑰，請按一下「停用網域驗證」切換鈕。Google Cloud Fraud Defense 則會忽略網域清單。 您必須自行執行網域驗證，方法是檢查所建立評估作業中的 tokenProperties.hostname 欄位。

9. 視您要為網站建立的 reCAPTCHA 金鑰類型而定，請執行適當的操作：

建立評分式 reCAPTCHA 金鑰

注意：在 Google Cloud 控制台中，建立分數型金鑰是預設選項。

1. 如要允許分數型金鑰與使用 amp-recaptcha-input 元件的 Accelerated Mobile Pages (AMP) 搭配運作，請開啟「Allow this key to work with AMP pages」(允許將這組金鑰用於 AMP 網頁) 切換鈕。

2. 在非正式環境中，如要指定金鑰在建立評估時應傳回的分數，請按照下列步驟操作：

   1. 按一下「下一步 (選用)」。
   2. 在「其他設定」步驟中，按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
   3. 使用「設定分數」滑桿，指定 0 到 1.0 之間的分數。
3. 按一下 [Create key] (建立金鑰)。

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

建立核取方塊 reCAPTCHA 金鑰

我們不建議使用核取方塊金鑰，因為這會增加使用者的困擾，也無法大幅提高準確率。

1. 按一下「下一步 (選用)」。
2. 在「其他設定」步驟中，開啟「要使用挑戰嗎？」 切換鈕。
3. 選取適當的「Challenge security」選項。

   驗證安全選項可控制系統提示使用者進行次要驗證的機率，系統會提示使用者根據指定類別選取圖片 (例如選取有摩托車或樓梯的圖片)。

   如要確保最佳反詐欺防護效果，請選取「嚴格」。

   如果選取「簡單」，使用者就不太可能看到視覺驗證問題。

4. 在非正式環境中，如要指定金鑰在建立評估時應傳回的分數，請按照下列步驟操作：

   1. 按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
   2. 使用「設定分數」滑桿，指定 0 到 1.0 之間的分數。
   3. 選取適當的「Challenge type」選項。
      • 自動有時會彈出驗證問題。
      • No CAPTCHA 不會顯示驗證問題，
      • 不需要解題的驗證方法會顯示圖片，但不會通過驗證。
   4. 按一下「建立金鑰」。

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

建立策略型驗證機制 reCAPTCHA 金鑰

1. 按一下「下一步 (選用)」。
2. 在「其他設定」步驟中，開啟「您要使用挑戰嗎？」 切換鈕。
3. 選取適當的「Challenge security」(驗證安全性) 選項。

   驗證問題安全性選項會定義向使用者顯示的 CAPTCHA 驗證問題複雜度和頻率。

   如要確保最佳反詐欺防護效果，請選取「Hard」。

   如果選取「Easy」(簡單)，系統會顯示較少且較簡單的 CAPTCHA 驗證問題，因此使用者較不容易看到提示。

4. 在非正式環境中，如要指定金鑰分數，以便在為金鑰建立評估時傳回，請按照下列步驟操作：

   1. 按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
   2. 使用「設定分數」滑桿，指定 0 到 1.0 之間的分數。
5. 選取觸發 CAPTCHA 驗證的分數門檻，這項設定適用於所有動作。
6. 按一下 [Create key] (建立金鑰)。

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

管理控制台

1. 前往 Google Cloud Fraud Defense 管理控制台。

   前往 Fraud Defense 管理控制台

2. 在「Label」(標籤) 欄位中，輸入可用來識別網站的名稱。
3. 如要建立以分數為依據的金鑰，請選取「以分數為依據 (v3)」。如要建立核取方塊金鑰，請選取「驗證問題 (v2)」。
4. 如要新增網域，請輸入網域名稱，然後按一下 。

   如要新增其他網域，請重複這個步驟。最多可新增 250 個網域。

5. 如果您是第一次使用 Google Cloud 控制台，請詳閱《服務條款》，然後勾選核取方塊。
6. 按一下「提交」。

如果您是第一次使用 Google Cloud 控制台，系統會建立 Google Cloud 專案並啟用必要的 API，方便您開始使用。如果您已有 Google Cloud 專案，系統會為專案啟用必要的 API，以便您開始使用。

gcloud

如要建立 reCAPTCHA 金鑰，請使用 gcloud recaptcha keys create 指令。

使用下列任何指令資料前，請先替換以下項目：

• INTEGRATION_TYPE：整合類型。 視金鑰類型而定，請指定下列值：
  • 分數型金鑰為 score。
  • checkbox：核取方塊鍵。
  • policy-based-challenge：以政策為準的驗證金鑰。
  注意：我們不建議使用 CHECKBOX，因為這會增加使用者困擾，且無法大幅提高準確率。 詳情請參閱常見問題。
• DISPLAY_NAME：金鑰名稱。通常是網站名稱。
• DOMAIN_NAME：允許使用金鑰的網站網域或子網域。

  請以逗號分隔的清單指定多個網域。

  如要在超過 250 個網域使用金鑰，請指定 --allow-all-domains 來停用網域驗證。Google Cloud Fraud Defense 則會忽略網域清單。您必須自行執行網域驗證，方法是檢查所建立評估作業中的 tokenProperties.hostname 欄位。

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

  注意： reCAPTCHA 金鑰是您指定的網域和子網域專屬。如果網站透過多個網域提供服務，您可以指定多個網域。如果指定網域 (例如 examplepetstore.com)，就不需要指定子網域 (例如 subdomain.examplepetstore.com)。網域清單變更最多可能需要 30 分鐘才會生效。
• DEFAULT_SCORE_THRESHOLD：如果金鑰採用政策型驗證，且未定義自訂分數門檻，這項設定會定義金鑰的一般驗證門檻。
• ACTION_SCORE_THRESHOLDS：如果是策略型驗證金鑰，這個欄位會指定動作和對應的門檻分數 (介於 0.0 和 1.0 之間)。例如：login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。
  注意：評估作業只會傳回經過任何挑戰後計算出的最終分數。Fraud Defense 會將初始分數與門檻值比較。

執行 gcloud recaptcha keys create 指令：

Linux、macOS 或 Cloud Shell

gcloud recaptcha keys create \
        --web \
        --display-name=DISPLAY_NAME  \
        --integration-type=INTEGRATION_TYPE \
        --domains=DOMAIN_NAME \

Windows (PowerShell)

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME `

Windows (cmd.exe)

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME ^

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

REST

如需金鑰類型和整合類型的 API 參考資訊，請參閱「金鑰」和「整合類型」。

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

• INTEGRATION_TYPE：整合類型。 視金鑰類型而定，請指定下列值：
  • 分數型金鑰為 SCORE。
  • CHECKBOX：核取方塊鍵。
  • POLICY_BASED_CHALLENGE：以政策為準的驗證金鑰。
  注意：我們不建議使用 CHECKBOX，因為這會增加使用者困擾，且無法大幅提高準確率。 詳情請參閱常見問題。
• DISPLAY_NAME：金鑰名稱。通常是網站名稱。
• DOMAIN_NAME：允許使用金鑰的網站網域或子網域。

  請以逗號分隔的清單指定多個網域。

  如要在超過 250 個網域使用金鑰，請指定 --allow-all-domains 來停用網域驗證。Google Cloud Fraud Defense 則會忽略網域清單。您必須自行執行網域驗證，方法是檢查所建立評估作業中的 tokenProperties.hostname 欄位。

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

  注意： reCAPTCHA 金鑰是您指定的網域和子網域專屬。如果網站透過多個網域提供服務，您可以指定多個網域。如果指定網域 (例如 examplepetstore.com)，就不需要指定子網域 (例如 subdomain.examplepetstore.com)。網域清單變更最多可能需要 30 分鐘才會生效。
• DEFAULT_SCORE_THRESHOLD：如果金鑰採用政策型驗證，且未定義自訂分數門檻，這項設定會定義金鑰的一般驗證門檻。
• ACTION_SCORE_THRESHOLDS：如果是政策型驗證金鑰，這個欄位會指定動作和對應的門檻分數 (介於 0.0 和 1.0 之間)。例如：login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。
  注意：評估作業只會傳回經過任何挑戰後計算出的最終分數。Fraud Defense 會將初始分數與門檻值比較。
• DEFAULT_SCORE_THRESHOLD：如果是政策型驗證金鑰，這項設定會定義金鑰的一般驗證門檻 (未定義自訂分數門檻時)。這項功能目前為預先發布版。
• ACTION_SCORE_THRESHOLDS：如果是政策型驗證金鑰，這個欄位會指定動作和對應的門檻分數 (介於 0.0 和 1.0 之間)。例如，login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。這項功能目前為預先發布版。
  注意：評估作業只會傳回經過任何挑戰後計算出的最終分數。系統會將 reCAPTCHA 計算出的初始分數與門檻值進行比較。

HTTP 方法和網址：

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

JSON 要求內文：

{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "INTEGRATION_TYPE"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

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

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

curl -X POST \
     -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"

PowerShell

注意：下列指令假設您已執行 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 POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-id/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

注意： 建立 reCAPTCHA 金鑰後，您可以編輯或刪除金鑰。刪除的金鑰無法復原。此外，您無法將 reCAPTCHA 金鑰從一個 Google Cloud 專案遷移到另一個專案。

(選用) 找出舊版 reCAPTCHA 密鑰

如要與不使用 reCAPTCHA Enterprise API 的第三方應用程式或內容管理系統 (CMS) 外掛程式 (例如 WordPress 或 Shopify) 整合，您需要與外掛程式支援版本 (v2 或 v3) 相符的金鑰，以及金鑰的舊版密鑰。如要進一步瞭解如何查看金鑰版本及設定 CMS 外掛程式，請參閱「整合管理控制台和 Google Cloud 控制台術語」。

每當您建立網站金鑰，reCAPTCHA 都會建立舊版 reCAPTCHA 密鑰 (舊版密鑰)，可與第三方應用程式搭配使用。

注意： 第三方應用程式或外掛程式通常會將這個舊版密鑰稱為「私密金鑰」或「密鑰」。

如需 reCAPTCHA 傳統版金鑰的密鑰，請將金鑰遷移至 Google Cloud上的 reCAPTCHA，然後找出舊版密鑰。

注意： 我們不建議在前端使用舊版密鑰，因為使用者會看到密鑰，攻擊者可能會濫用您的應用程式。

如要找出舊版密鑰，請按照下列步驟操作：

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

   前往 Fraud Defense

2. 選取「金鑰」分頁標籤。

3. 在「reCAPTCHA Keys」(reCAPTCHA 金鑰) 專區中，找出您建立的 reCAPTCHA 金鑰，然後按一下該金鑰。

   

4. 在「Key details」(金鑰詳細資料) 頁面中，前往「Integration」(整合) 分頁，然後按一下「Use legacy key」(使用舊版金鑰) 或「Integrate with a third-party service or plugin」(與第三方服務或外掛程式整合)。對話方塊隨即開啟，並顯示舊版密鑰。

   

後續步驟

• 協調管理控制台和 Google Cloud 控制台術語。
• 在網頁中安裝分數制金鑰。
• 在網頁上安裝核取方塊金鑰。
• 在網頁上安裝策略型驗證金鑰。