与适用于移动应用的 Google Cloud Armor 集成

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

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

准备工作

1. 启用 reCAPTCHA Enterprise API。

   启用 API

2. 确定要保护的操作。

实现 reCAPTCHA 操作令牌

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

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

1. 为您的移动应用创建操作令牌密钥。

   控制台

   1. 在 Google Cloud 控制台中，前往 reCAPTCHA Enterprise 页面。

      转到 reCAPTCHA Enterprise

   2. 验证项目名称是否显示在页面顶部的项目选择器中。

      如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。

   3. 点击创建密钥。

      
   4. 在显示名字段中，输入密钥的显示名。
   5. 根据您要为哪类应用创建用于 WAF 的 reCAPTCHA 密钥，执行适当的操作：
   注意：只有与 Google Cloud Armor 集成时，才支持在移动应用上为 WAF 创建 reCAPTCHA 密钥。对于此集成，您只能为移动应用创建操作令牌密钥。

   为 iOS 应用的 WAF 创建 reCAPTCHA 密钥

   我们建议您为每个 iOS 应用创建一个 reCAPTCHA 密钥。

   1. 在选择平台类型菜单中，选择 iOS 应用。
      
   1. 在 iOS 软件包 ID 列表部分中，点击添加 iOS 软件包 ID。

   2. 在软件包 ID 字段中，输入您的 iOS 软件包 ID 的名称。

   3. 可选：如需添加其他软件包 ID，请点击添加 iOS 软件包 ID，然后在软件包 ID 字段中输入 iOS 软件包 ID 的名称。

   4. 可选：提供 Apple Developer 设置。

      我们建议您提供这些数据，因为它可以让 reCAPTCHA Enterprise 为您的流量提供更准确的风险评分。

      输入以下信息：

      • 私钥 (.p8)：在 Apple 开发者中心的“证书、标识符和个人资料”下生成。
      • 密钥标识符：Apple 开发者密钥标识符（10 个字符的字符串）。
      • 团队 ID：拥有用于构建应用的预配配置文件的 Apple 团队 ID（10 个字符的字符串）。
   5. 展开软件包 ID 验证和密钥类型。
      1. 如需为 WAF 创建 reCAPTCHA 密钥，请执行以下操作：
         1. 开启 Web 应用防火墙 (WAF) 切换开关。
         2. 从服务菜单中，选择 Cloud Armor。
         3. 从功能菜单中选择操作令牌。
      2. 如需保护软件包 ID 的 reCAPTCHA 密钥，请确保停用软件包 ID 验证切换开关已关闭。

      3. 对于非生产环境，如果您想指定密钥在为其创建任何评估时返回的分数，请执行以下操作：

         1. 点击这是一个测试密钥切换开关。
         2. 在 Score 框中，指定一个 0 到 1.0 之间的得分。
   6. 点击创建密钥。

   新创建的密钥会列在 reCAPTCHA 密钥页面上。

   为 Android 应用的 WAF 创建 reCAPTCHA 密钥

   1. 在选择平台类型菜单中，选择 Android 应用。
      
   2. 在 Android 软件包列表部分中，点击添加 Android 软件包。

   3. 在 Android 软件包字段中，输入您的 Android 软件包的名称。

      
   4. 可选：要添加其他软件包，请点击添加 Android 软件包，然后在 Android 软件包字段中输入其他 Android 软件包的名称。
   5. 展开软件包名称验证、应用分发和测试密钥。
   1. 如需为 WAF 创建 reCAPTCHA 密钥，请执行以下操作：
      1. 开启 Web 应用防火墙 (WAF) 切换开关。
      2. 从服务菜单中，选择 Cloud Armor。
      3. 从功能菜单中选择操作令牌。
   2. 如需强制规定仅在您的应用内使用 reCAPTCHA 密钥，请关闭停用软件包名称验证切换开关。
   3. 如果您要为除了 Google Play 商店以外的其他应用商店提供的应用创建密钥，请开启支持从 Google Play 商店以外的地方分发的应用。

   4. 对于非生产环境，如果您想指定密钥在为其创建任何评估时返回的分数，请执行以下操作：

      1. 点击这是一个测试密钥切换开关。
      2. 在 Score 框中，指定一个 0 到 1.0 之间的得分。
   6. 点击创建密钥。

   新创建的密钥会列在 reCAPTCHA 密钥页面上。

   gcloud（iOS 版）

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

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

   在使用下面的命令数据之前，请先进行以下替换：

   • 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 命令。

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

   在使用下面的命令数据之前，请先进行以下替换：

   • 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)

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

   在使用任何请求数据之前，请先进行以下替换：

   • 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，或使用 Cloud Shell（自动登录到 gcloud CLI）使用您的用户帐号登录了 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)

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

   在使用任何请求数据之前，请先进行以下替换：

   • 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，或使用 Cloud Shell（自动登录到 gcloud CLI）使用您的用户帐号登录了 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"
     }
   }
   
   

2. 使用您创建的操作令牌密钥在您的移动应用上集成 reCAPTCHA Enterprise 移动 SDK。有关说明，请参阅与您的移动应用类型对应的文档。

   • 对于 Android，请参阅将 WAF 密钥与 Android 应用集成。
   • 对于 iOS，请参阅将 WAF 密钥与 iOS 应用集成。

3. 从 reCAPTCHA Enterprise 收到令牌后，请将令牌附加到预定义的请求标头，格式如下：

   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 Enterprise for WAF 的功能后，您必须配置 Google Cloud Armor 安全政策，以评估 reCAPTCHA Enterprise 令牌以进行机器人管理。

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

后续步骤

• 配置聊天机器人管理规则。