在應用程式伺服器上設定 reCAPTCHA Express

如果無法在用戶端整合 reCAPTCHA JavaScript 或行動裝置 SDK，例如為了保護 API 端點，您可以在應用程式伺服器上設定 reCAPTCHA Express。

reCAPTCHA Express 是一項功能，可讓您建立評估，不必整合用戶端或使用用戶端信號。reCAPTCHA Express 只會使用後端信號產生 reCAPTCHA 風險分數。您可以根據這項風險分數，決定是否要處理要求、重新導向至驗證頁面，或是記錄要求以供日後分析。

事前準備

1. 在 Google Cloud 控制台的專案選擇器頁面中，選取或建立 Google Cloud 專案。

   選取或建立專案所需的角色

   • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
   • 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

   前往專案選取器

   記下 Google Cloud 專案 ID，以供後續使用。

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

3. 啟用 reCAPTCHA Enterprise API。

   啟用 API 時所需的角色

   如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

4. 建立用於驗證的 API 金鑰：

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

      前往「憑證」

   2. 按一下「建立憑證」，然後選取「API 金鑰」。

   3. 請記下 API 金鑰，稍後會用到。

建立 reCAPTCHA Express 金鑰

如要導入 reCAPTCHA Express，請建立 reCAPTCHA Express 金鑰。

1. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

2. gcloud

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

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

   • INTEGRATION_TYPE：整合類型。 指定 score。
   • DISPLAY_NAME：金鑰名稱，通常是網站名稱。

   執行 gcloud recaptcha keys create 指令：

   Linux、macOS 或 Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME

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

   REST

   如要查看金鑰類型和整合類型的 API 參考資料，請參閱「金鑰」和「整合類型」。

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

   • INTEGRATION_TYPE：整合類型。 指定 score。
   • DISPLAY_NAME：金鑰名稱，通常是網站名稱。
   • 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",
     "expressSettings": {}
   }
   
   

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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "expressSettings": {
   }
   }
   
   

請記下快速鍵，稍後會用到。

建立評估

如要從應用程式伺服器向 reCAPTCHA 提出要求，請使用 projects.assessments.create 方法建立評估。

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

• API_KEY：您為驗證建立的 API 金鑰。
• EXPRESS_KEY：您為應用程式建立的 reCAPTCHA Express 金鑰。
• USER_IP_ADDRESS：使用者裝置在與此事件相關的請求中提供的 IP 位址。
• HEADER_INFO：選用。用戶端傳送至應用程式伺服器的 HTTP 標頭。這是字串陣列，包含 `[key:value]` 格式的要求標頭。例如 `[key:value, key:value,...]`。建議您盡可能分享標題，並依規定順序排列。請確保同一工作階段中所有要求的標頭順序一致。
• JA3_FINGERPRINT：選用。JA3 是 TLS 用戶端問候封包特定欄位的 MD5 指紋。詳情請參閱「JA3 - A method for profiling SSL/TLS Clients」。
• URI_NAME：選用。使用者存取的 URI。
• USER_AGENT：選用。使用者裝置在與這個事件相關的請求中提供的使用者代理程式。
• ACCOUNT_ID：選用。使用者帳戶的專屬永久 ID，例如經過雜湊處理的帳戶名稱。

HTTP 方法和網址：

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

JSON 要求內文：

{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

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

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

解讀分數

reCAPTCHA Express 只會傳回兩個分數：0.3 和 0.7。0.3 表示使用者互動的風險較高，可能是詐欺行為；0.7 表示使用者互動的風險較低，可能是正當活動。

如果信號不足，reCAPTCHA Express 預設會傳回 0.7。

後續步驟

• 瞭解如何解讀風險分數。
• 瞭解如何在 WAF 層使用 reCAPTCHA Express。