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

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

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

如要完成整合，您必須導入一或多項 reCAPTCHA for WAF 功能，並設定 Google Cloud Armor 安全性政策。不過，在行動應用程式上與 Google Cloud Armor 整合時，您只能導入 reCAPTCHA 動作權杖。

事前準備

啟用 reCAPTCHA Enterprise API。

Enable the API
找出要保護的動作。

實作 reCAPTCHA 動作權杖

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

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

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

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

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

使用下方的任何指令資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
- BUNDLE_IDs：允許使用金鑰的應用程式的 iOS 組合 ID。以逗號分隔清單的形式指定多個套件 ID。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。指定 action-token。
- WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Google 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 金鑰時，僅支援與 Google Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用下方的任何指令資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是網站名稱。
- PACKAGE_NAMES：允許使用金鑰的應用程式的 Android 套件名稱。以逗號分隔清單的形式指定多個套件名稱。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。指定 action-token。
- WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Google 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 金鑰時，僅支援與 Google Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用任何要求資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是應用程式名稱。
- BUNDLE_IDs：允許使用金鑰的應用程式的 iOS 組合 ID。以逗號分隔清單的形式指定多個套件 ID。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。指定 action-token。
- WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Google 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 金鑰時，僅支援與 Google Cloud Armor 整合。進行這項整合時，您只能為行動應用程式建立動作權杖金鑰。

使用任何要求資料之前，請先替換以下項目：
- DISPLAY_NAME：金鑰名稱。通常是應用程式名稱。
- PACKAGE_NAMES：允許使用金鑰的應用程式的 Android 套件名稱。以逗號分隔清單的形式指定多個套件名稱。
- WAF_FEATURE：網路應用程式防火牆功能的名稱。指定 action-token。
- WAF_SERVICE：網路應用程式防火牆服務供應商的名稱。為 Google 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)
 }

設定 Google Cloud Armor 安全性政策

導入 reCAPTCHA for WAF 的功能後，您必須設定 Google Cloud Armor 安全性政策，評估 reCAPTCHA 權杖，以管理機器人。

如要瞭解如何設定 Google 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 分數。

後續步驟

設定機器人管理規則。

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

事前準備

實作 reCAPTCHA 動作權杖

控制台

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

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

gcloud (iOS)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

gcloud (Android)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST (iOS)

curl

PowerShell

REST (Android)

curl

PowerShell

Android

iOS

設定 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)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST (iOS)

curl

PowerShell

REST (Android)

curl

PowerShell

Android

iOS

設定 Google Cloud Armor 安全性政策

取得 reCAPTCHA 分數

後續步驟

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