本頁面由 Cloud Translation API 翻譯而成。

與 Google Cloud Armor 整合，適用於行動應用程式

本文說明如何在行動應用程式中，整合 reCAPTCHA 與 Cloud Armor 的功能。

如要完成整合，請導入一或多項 reCAPTCHA 功能，並設定 Cloud Armor 安全性政策。不過，您只能實作 reCAPTCHA 動作權杖，以便在行動應用程式中與 Cloud Armor 整合。

事前準備

啟用 reCAPTCHA Enterprise API。

Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
找出要保護的動作。

實作 reCAPTCHA 動作權杖

您必須在行動應用程式上執行 reCAPTCHA，才能產生動作權杖。reCAPTCHA 產生動作權杖後，您可以在需要保護任何使用者動作 (例如 checkout) 的地方，將動作權杖附加至預先定義的要求標頭。根據預設，動作權杖的效期為 30 分鐘，但可能會因流量而異。您必須在權杖到期前，將動作權杖附加至預先定義的要求標頭，Cloud Armor 才能評估權杖屬性。

如要實作 reCAPTCHA 動作權杖，請按照下列步驟操作：

為行動應用程式建立動作權杖金鑰。
控制台
1. 前往 Google Cloud 控制台的「reCAPTCHA」reCAPTCHA頁面。
  
  前往 reCAPTCHA
2. 確認頁面頂端的資源選取器中顯示了專案名稱。
  
  如果沒有看到專案名稱，請按一下資源選取器，然後選取專案。
3. 按一下「建立金鑰」。
4. 在「顯示名稱」欄位中，輸入金鑰的顯示名稱。
5. 視要為 WAF 建立 reCAPTCHA 金鑰的應用程式類型而定，請執行適當的動作：
gcloud (iOS)

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

注意：建立行動應用程式專用網路應用程式防火牆的 reCAPTCHA 金鑰時，僅支援與 Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用下列任何指令資料之前，請先替換以下項目：
- 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 指令。

注意：建立行動應用程式專用網路應用程式防火牆的 reCAPTCHA 金鑰時，僅支援與 Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用下列任何指令資料之前，請先替換以下項目：
- 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)

注意：建立行動應用程式專用網路應用程式防火牆的 reCAPTCHA 金鑰時，僅支援與 Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用任何要求資料之前，請先替換以下項目：
- 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

注意： 下列指令假設您已執行 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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT", "displayName": "DISPLAY_NAME", "iosSettings": { "allowAllBundleIds": false, "allowedBundleIds": [ BUNDLE_IDS ] }, "labels": {}, "wafSettings": { "wafService": "CA", "wafFeature": "ACTION_TOKEN" } }
REST (Android)

注意：建立行動應用程式專用網路應用程式防火牆的 reCAPTCHA 金鑰時，僅支援與 Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用任何要求資料之前，請先替換以下項目：
- 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

注意： 下列指令假設您已執行 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/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 安全性政策，以及如何搭配使用動作權杖金鑰與安全性政策，請參閱「設定機器人管理規則」。

取得 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 分數。

後續步驟

設定機器人管理規則。

與 Google Cloud Armor 整合，適用於行動應用程式

事前準備

實作 reCAPTCHA 動作權杖

控制台

為 iOS 應用程式的 WAF 建立 reCAPTCHA 金鑰

為 Android 應用程式建立 WAF 適用的 reCAPTCHA 金鑰

gcloud (iOS)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

gcloud (Android)