此页面由 Cloud Translation API 翻译。

与 Google Cloud Armor for Mobile Applications 集成

本文档介绍了如何在移动应用中将 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
2. 验证项目名称是否显示在页面顶部的项目选择器中。
  
  如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。
3. 点击创建密钥。
4. 在显示名字段中，输入密钥的显示名。
5. 根据要为其创建 reCAPTCHA WAF 密钥的应用类型，执行适当的操作：
gcloud (iOS)

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

注意：仅当与 Cloud Armor 集成时，才支持在移动应用上为 WAF 创建 reCAPTCHA 密钥。对于此集成，您只能为移动应用创建操作令牌密钥。

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

注意：仅当与 Cloud Armor 集成时，才支持在移动应用上为 WAF 创建 reCAPTCHA 密钥。对于此集成，您只能为移动应用创建操作令牌密钥。

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

注意：仅当与 Cloud Armor 集成时，才支持在移动应用上为 WAF 创建 reCAPTCHA 密钥。对于此集成，您只能为移动应用创建操作令牌密钥。

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

注意：仅当与 Cloud Armor 集成时，才支持在移动应用上为 WAF 创建 reCAPTCHA 密钥。对于此集成，您只能为移动应用创建操作令牌密钥。

在使用任何请求数据之前，请先进行以下替换：
- DISPLAY_NAME：密钥的名称。通常是应用名称。
- PACKAGE_NAMES：获准使用该密钥的应用的 Android 软件包名称。以英文逗号分隔的列表形式指定多个软件包名称。
- WAF_FEATURE：WAF 功能的名称。指定 action-token。
- WAF_SERVICE：WAF 服务提供商的名称。为 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" } }
在移动应用中集成您创建的 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 for Mobile Applications 集成

准备工作

实现 reCAPTCHA 操作令牌

控制台

为 iOS 应用创建 reCAPTCHA WAF 密钥

为 Android 应用创建 reCAPTCHA WAF 密钥

gcloud (iOS)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

gcloud (Android)