此页面由 Cloud Translation API 翻译。

与 Google Cloud Armor for Mobile Applications 集成

本文档介绍了如何在移动应用中将 reCAPTCHA 的 WAF 功能与 Google Cloud Armor 集成。

如需完成集成，您必须实现 reCAPTCHA for WAF 的一项或多项功能，并配置 Google Cloud Armor 安全政策。不过，您只能在移动应用中实现 reCAPTCHA 操作令牌，以便与 Google Cloud Armor 集成。

准备工作

启用 reCAPTCHA Enterprise API。

Enable the API
确定要保护的操作。

实现 reCAPTCHA 操作令牌

您必须在移动应用上运行 reCAPTCHA 才能生成操作令牌。 reCAPTCHA 生成操作令牌后，您可以在需要保护任何用户操作（例如 checkout）的情况下将操作令牌附加到预定义的请求标头。默认情况下，操作令牌的有效期为 30 分钟，但可能会因流量而异。您必须在操作令牌到期之前将其附加到预定义的请求标头，使得 Google Cloud Armor 可以评估令牌属性。

如需实现 reCAPTCHA 操作令牌，请执行以下操作：

为移动应用创建 action-token 密钥。
控制台
1. 在 Google Cloud 控制台中，前往 reCAPTCHA 页面。
  
  前往 reCAPTCHA
2. 验证项目名称是否显示在页面顶部的项目选择器中。
  
  如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。
3. 点击创建密钥。
4. 在显示名字段中，输入密钥的显示名。
5. 根据您要为 WAF 创建 reCAPTCHA 密钥的应用类型，执行适当的操作：
gcloud (iOS)

如需创建 reCAPTCHA 键，请使用 gcloud recaptcha keys create 命令。

注意：仅支持在移动应用中为 WAF 创建 reCAPTCHA 密钥，前提是与 Google Cloud Armor 集成。对于此集成，您只能为移动应用创建操作令牌密钥。

在使用下面的命令数据之前，请先进行以下替换：
- DISPLAY_NAME：密钥的名称。通常是网站名称。
- BUNDLE_IDs：获准使用该密钥的应用的 iOS 软件包 ID。以英文逗号分隔的列表形式指定多个软件包 ID。
- WAF_FEATURE：WAF 功能的名称。指定 action-token。
- WAF_SERVICE：WAF 服务提供商的名称。为 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 命令。

注意：仅支持在移动应用中为 WAF 创建 reCAPTCHA 密钥，前提是与 Google Cloud Armor 集成。对于此集成，您只能为移动应用创建操作令牌密钥。

在使用下面的命令数据之前，请先进行以下替换：
- DISPLAY_NAME：密钥的名称。通常是网站名称。
- PACKAGE_NAMES：获准使用该密钥的应用的 Android 软件包名称。以英文逗号分隔的列表形式指定多个软件包名称。
- WAF_FEATURE：WAF 功能的名称。指定 action-token。
- WAF_SERVICE：WAF 服务提供商的名称。为 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)

注意：仅支持在移动应用中为 WAF 创建 reCAPTCHA 密钥，前提是与 Google Cloud Armor 集成。对于此集成，您只能为移动应用创建操作令牌密钥。

在使用任何请求数据之前，请先进行以下替换：
- DISPLAY_NAME：密钥的名称。通常是应用名称。
- BUNDLE_IDs：获准使用该密钥的应用的 iOS 软件包 ID。以英文逗号分隔的列表形式指定多个软件包 ID。
- WAF_FEATURE：WAF 功能的名称。指定 action-token。
- WAF_SERVICE：WAF 服务提供商的名称。为 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）

注意：仅支持在移动应用中为 WAF 创建 reCAPTCHA 密钥，前提是与 Google Cloud Armor 集成。对于此集成，您只能为移动应用创建操作令牌密钥。

在使用任何请求数据之前，请先进行以下替换：
- DISPLAY_NAME：密钥的名称。通常是应用名称。
- PACKAGE_NAMES：获准使用该密钥的应用的 Android 软件包名称。以英文逗号分隔的列表形式指定多个软件包名称。
- WAF_FEATURE：WAF 功能的名称。指定 action-token。
- WAF_SERVICE：WAF 服务提供商的名称。为 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，并使用您创建的 action-token 密钥。如需了解相关说明，请参阅与您的移动应用类型对应的文档。
- 对于 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 的功能后，您必须配置用于评估 reCAPTCHA 令牌以进行聊天机器人管理的 Google Cloud Armor 安全政策。

如需了解如何配置 Google Cloud Armor 安全政策以及如何将操作令牌键与安全政策搭配使用，请参阅配置用于机器人管理的规则。

后续步骤

配置机器人管理规则。

与 Google Cloud Armor for Mobile Applications 集成

准备工作

实现 reCAPTCHA 操作令牌

控制台

为 WAF 创建适用于 iOS 应用的 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 安全政策

后续步骤