本文說明如何在行動應用程式中，整合 reCAPTCHA 與 Cloud Armor 的功能。
如要完成整合，請導入一或多項 reCAPTCHA 功能，並設定 Cloud Armor 安全性政策。不過，您只能實作 reCAPTCHA 動作權杖，以便在行動應用程式中與 Cloud Armor 整合。
事前準備
啟用 reCAPTCHA Enterprise API。
找出要保護的動作。
實作 reCAPTCHA 動作權杖
您必須在行動應用程式上執行 reCAPTCHA，才能產生動作權杖。reCAPTCHA 產生動作權杖後，您可以在需要保護任何使用者動作 (例如 checkout) 的位置，將動作權杖附加至預先定義的要求標頭。根據預設，動作權杖的效期為 30 分鐘，但可能會因流量而異。
您必須在權杖過期前，將動作權杖附加至預先定義的要求標頭，Cloud Armor 才能評估權杖屬性。
如要實作 reCAPTCHA 動作權杖，請按照下列步驟操作：
為行動應用程式建立動作權杖金鑰。
控制台
前往 Google Cloud 控制台的「reCAPTCHA」reCAPTCHA頁面。
確認頁面頂端的資源選取器中顯示了專案名稱。
如果沒有看到專案名稱，請按一下資源選取器，然後選取專案。
- 按一下「建立金鑰」。
- 在「顯示名稱」欄位中，輸入金鑰的顯示名稱。
- 視您要為 WAF 建立 reCAPTCHA 金鑰的應用程式類型而定，請執行適當的動作：
- 在「Application type」部分，選取「iOS」。
- 在「iOS 軟體包 ID 清單」部分中，按一下「新增 iOS 軟體包 ID」。
在「Bundle ID」(套件 ID) 欄位中，輸入 iOS 套件 ID 的名稱。
- 選用：如要新增其他軟體包 ID，請按一下「新增 iOS 軟體包 ID」， 並在「軟體包 ID」欄位中輸入 iOS 軟體包 ID 名稱。
- 如要保護軟體包 ID 的 reCAPTCHA 金鑰，請務必關閉「停用軟體包 ID 驗證」切換鈕。
選用：提供 Apple Developer 設定。
建議您提供這項資料，因為 reCAPTCHA 可以根據這些資料，更準確地評估流量風險分數。
輸入下列資訊：
- 私密金鑰 (.p8)：在 Apple Developer Center 的「Certificates, Identifiers & Profiles」下方產生。
- 金鑰 ID：Apple 開發人員金鑰 ID (10 個字元的字串)。
- 團隊 ID：擁有用於建構應用程式的佈建設定檔的 Apple 團隊 ID (10 個字元的字串)。
- 選用：按一下「下一步 (選用)」。
- 如要建立 WAF 適用的 reCAPTCHA 金鑰，請按照下列步驟操作：
- 在「其他設定」中，開啟「
- 在「其他設定」中，開啟「您是否會在網頁應用程式防火牆 (WAF) 中部署這個金鑰？」切換按鈕。
- 從「Service」選項中，選取「Cloud Armor」。
- 在「功能」選項中，選取「動作」。
-
如要為非正式版環境指定分數，讓金鑰在建立任何評估時傳回該分數，請按照下列步驟操作：
- 在「其他設定」中，按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
- 使用「設定分數」滑桿指定介於 0 到 1.0 的分數。
- 按一下 [Create key] (建立金鑰)。
- 在「Application type」部分，選取「Android」。
- 在「Android package list」(Android 套件清單) 區段中，按一下「Add Android package」(新增 Android 套件)。
- 在「Android package」(Android 套件) 欄位中，輸入 Android 套件的名稱。
- 選用：如要新增其他套件，請按一下「新增 Android 套件」，然後在「Android 套件」欄位中輸入其他 Android 套件的名稱。
- 如要強制規定 reCAPTCHA 金鑰只能在應用程式中使用，請關閉「停用套件名稱驗證」切換鈕。
- 如果您想為 Google Play 商店以外的應用程式商店建立金鑰，請開啟「支援在 Google Play 商店以外平台發布應用程式」。
- 選用：按一下「下一步 (選用)」。
- 如要建立 WAF 適用的 reCAPTCHA 金鑰，請按照下列步驟操作：
- 在「其他設定」中，開啟「
- 在「其他設定」中，開啟「您是否會在網頁應用程式防火牆 (WAF) 中部署這個金鑰？」切換按鈕。
- 從「Service」選項中，選取「Cloud Armor」。
- 在「功能」選項中，選取「動作」。
-
如要為非正式版環境指定分數，讓金鑰在建立任何評估時傳回該分數，請按照下列步驟操作：
- 在「其他設定」中，按一下「您建立的這組金鑰是否僅供測試之用？」切換鈕。
- 使用「設定分數」滑桿指定介於 0 到 1.0 的分數。
- 按一下 [Create key] (建立金鑰)。
為 iOS 應用程式的 WAF 建立 reCAPTCHA 金鑰
建議您為每個 iOS 應用程式建立一個 reCAPTCHA 金鑰。
新建立的金鑰會列在「reCAPTCHA keys」(reCAPTCHA 金鑰) 頁面。
為 Android 應用程式建立 WAF 適用的 reCAPTCHA 金鑰
新建立的金鑰會列在「reCAPTCHA keys」(reCAPTCHA 金鑰) 頁面。
gcloud (iOS)
如要建立 reCAPTCHA 金鑰，請使用 gcloud recaptcha keys create 指令。
使用下列任何指令資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
- BUNDLE_IDs：允許使用金鑰的應用程式的 iOS 組合 ID。 以逗號分隔清單的形式指定多個套件 ID。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。
指定
action-token。 - WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Cloud Armor 指定
CA。
執行 gcloud recaptcha keys create 指令：
Linux、macOS 或 Cloud Shell
gcloud recaptcha keys create \ --display-name=DISPLAY_NAME \ --ios --bundle-ids=BUNDLE_IDs \ --waf-feature=WAF_FEATURE \ --waf-service=WAF_SERVICE
Windows (PowerShell)
gcloud recaptcha keys create ` --display-name=DISPLAY_NAME ` --ios --bundle-ids=BUNDLE_IDs ` --waf-feature=WAF_FEATURE ` --waf-service=WAF_SERVICE
Windows (cmd.exe)
gcloud recaptcha keys create ^ --display-name=DISPLAY_NAME ^ --ios --bundle-ids=BUNDLE_IDs ^ --waf-feature=WAF_FEATURE ^ --waf-service=WAF_SERVICE
回應包含新建立的 reCAPTCHA 金鑰。
gcloud (Android)
如要建立 reCAPTCHA 金鑰，請使用 gcloud recaptcha keys create 指令。
使用下列任何指令資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
- PACKAGE_NAMES：允許使用金鑰的應用程式的 Android 套件名稱。以逗號分隔清單的形式指定多個套件名稱。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。
指定
action-token。 - WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Cloud Armor 指定
CA。
執行 gcloud recaptcha keys create 指令：
Linux、macOS 或 Cloud Shell
gcloud recaptcha keys create \ --display-name=DISPLAY_NAME \ --android --package-names=PACKAGE_NAMES \ --waf-feature=WAF_FEATURE \ --waf-service=WAF_SERVICE
Windows (PowerShell)
gcloud recaptcha keys create ` --display-name=DISPLAY_NAME ` --android --package-names=PACKAGE_NAMES ` --waf-feature=WAF_FEATURE ` --waf-service=WAF_SERVICE
Windows (cmd.exe)
gcloud recaptcha keys create ^ --display-name=DISPLAY_NAME ^ --android --package-names=PACKAGE_NAMES ^ --waf-feature=WAF_FEATURE ^ --waf-service=WAF_SERVICE
回應包含新建立的 reCAPTCHA 金鑰。
REST (iOS)
使用任何要求資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是應用程式名稱。
- BUNDLE_IDs：允許使用金鑰的應用程式的 iOS 組合 ID。 以逗號分隔清單的形式指定多個套件 ID。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。
指定
action-token。 - WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Cloud Armor 指定
CA。
HTTP 方法和網址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
JSON 要求主體：
{ "displayName": "DISPLAY_NAME", "iosSettings": { "allowedBundleIds": "BUNDLE_IDS" }, 'wafSettings': " { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為
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
將要求主體儲存在名為
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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT", "displayName": "DISPLAY_NAME", "iosSettings": { "allowAllBundleIds": false, "allowedBundleIds": [ BUNDLE_IDS ] }, "labels": {}, "wafSettings": { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }REST (Android)
使用任何要求資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是應用程式名稱。
- PACKAGE_NAMES：允許使用金鑰的應用程式的 Android 套件名稱。以逗號分隔清單的形式指定多個套件名稱。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。
指定
action-token。 - WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Cloud Armor 指定
CA。
HTTP 方法和網址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
JSON 要求主體：
{ "displayName": "DISPLAY_NAME", "androidSettings": { "allowedPackageNames":"PACKAGE_NAMES" }, 'wafSettings': " { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為
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
將要求主體儲存在名為
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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy", "displayName": "DISPLAY_NAME", "androidSettings": { "allowAllPackageNames": false, "allowedPackageNames": [ PACKAGE_NAMES ], "supportNonGoogleAppStoreDistribution": false }, "labels": {}, "wafSettings": { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }在行動應用程式中整合 reCAPTCHA 行動版 SDK，並使用您建立的動作權杖金鑰。如需操作說明，請參閱與行動應用程式類型相應的文件。
- 如要瞭解 Android 相關資訊，請參閱「將 WAF 金鑰與 Android 應用程式整合」。
- 如要瞭解 iOS 應用程式，請參閱「將 WAF 金鑰與 iOS 應用程式整合」。
從 reCAPTCHA 收到權杖後，請將權杖附加至預先定義的要求標頭，格式如下：
X-Recaptcha-Token: value-of-your-action-token
以下程式碼範例說明如何附加權杖：
Android
Java 程式碼範例
// This example shows how to send an HTTP request to the backend server // attached with the reCAPTCHA token in the header. // // @param serverUrl: the URL of the backend server. // @param rceToken: reCAPTCHA token that is attached to the header of the // HTTP request. public static void sendRequestToServerWithRceToken( String serverUrl, String rceToken) throws JSONException, IOException { URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl)); HttpURLConnection connection = (HttpURLConnection) url.openConnection(); connection.setRequestProperty("X-Recaptcha-Token", rceToken); try { String requestBody = "['']"; sendRequest(connection, requestBody, "AccessWithRceToken", "GET"); } finally { connection.disconnect(); } } private static void sendRequest( HttpURLConnection connection, String requestString, String requestName, String action) throws IOException { connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS); connection.setReadTimeout(HTTP_READ_TIMEOUT_MS); connection.setRequestProperty("Content-type", CONTENT_TYPE); connection.setRequestProperty( "Content-Length", Integer.toString(Utf8.encodedLength(requestString))); connection.setRequestMethod(action); connection.setDoOutput(true); connection.connect(); try (OutputStream postStream = connection.getOutputStream()) { postStream.write(requestString.getBytes(UTF_8)); } int responseCode = connection.getResponseCode(); String response = connection.getResponseMessage(); if (responseCode != HttpURLConnection.HTTP_OK) { throw new IOException( String.format( "Failed to complete request.\nResponse code:%s\nError Detail:\n%s", responseCode, response)); } }
iOS
Swift 程式碼範例
// This example shows how to send an HTTP request to the backend server // attached with the reCAPTCHA token in the header. // @param serverUrl: the URL of the backend server. // @param rceToken: reCAPTCHA token that is attached to the header of // the HTTP request. public static func accessWafServer(rceToken: String, serverUrl: String) async throws -> String { let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl) var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET") request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token") let data = try await HttpHelper.getDataFromServer(request) return String(decoding: data, as: UTF8.self) }
設定 Cloud Armor 安全性政策
導入 reCAPTCHA for WAF 的功能後，您必須設定 Cloud Armor 安全性政策，評估 reCAPTCHA 權杖來管理機器人。
如要瞭解如何設定 Cloud Armor 安全性政策，以及如何搭配安全性政策使用 action-token 鍵，請參閱「設定機器人管理規則」。
取得 reCAPTCHA 分數
如為 reCAPTCHA 動作符記，您可以從 X-Recaptcha-Wafdata 標頭取得 reCAPTCHA 分數。您可以根據這些分數，為使用者要求設定任何需要執行的自訂動作。
以下範例顯示 X-Recaptcha-Wafdata 標頭範例：
X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n
您也可以在 Google Cloud Armor 記錄檔中查看 reCAPTCHA 分數。