实现适用于 WAF 和 Google Cloud Armor 的 reCAPTCHA Enterprise

本文档介绍了如何为 Google Cloud Armor 实现 reCAPTCHA 质询页面reCAPTCHA action-tokensreCAPTCHA session-tokens

准备工作

在使用 reCAPTCHA 质询页面、操作令牌或会话令牌之前,请先启用 reCAPTCHA Enterprise API。

  1. 在控制台中,转到 reCAPTCHA Enterprise API 页面。

    转到 reCAPTCHA Enterprise API

  2. 验证项目的名称是否显示在页面顶部的项目选择器中。如果您没有看到项目名称,请点击项目选择器,然后选择您的项目。

  3. 点击启用

实现 reCAPTCHA 质询页面

当您实现 reCAPTCHA 质询页面时,reCAPTCHA Enterprise 会确定是否必须向用户显示人机识别系统质询。因此,人机识别系统质询可能并不适用于所有用户。

如需实现 reCAPTCHA 质询页面,请执行以下操作:

  1. 创建 reCAPTCHA WAF 质询页面网站密钥。

    控制台

    1. 在控制台中,转到 reCAPTCHA Enterprise 页面。

      转到 reCAPTCHA Enterprise

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

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

    3. 点击创建密钥

    4. 显示名字段中,输入密钥的显示名。
    5. 选择平台类型下拉菜单中,选择网站

    6. 展开 Web 应用防火墙 (WAF)、网域验证、AMP 网页和验证部分。
    7. 开启 Web 应用防火墙 (WAF) 切换开关。
    8. 功能下拉菜单中选择挑战页面

    9. 开启停用域名验证

      当您对验证页面的网站密钥停用域名验证后,Google Cloud Armor 会验证该域名。

    10. 点击创建密钥
    11. 新创建的密钥会列在 reCAPTCHA 密钥页面上。

    gcloud

    如需创建 WAF 网站密钥,请使用 gcloud recaptcha keys create 命令:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    请提供以下值:

    • DISPLAY_NAME:密钥的名称。通常是网站名称。
    • WAF_FEATURE:WAF 功能的名称。 指定 challenge-page
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • INTEGRATION_TYPE:集成类型。 指定 INVISIBLE
    • DOMAIN_NAME:获准使用相应密钥的网站的网域或子网域。以逗号分隔列表的形式指定多个网域。 可选:指定 --allow-all-domains 可停用网域验证。

      当您对验证页面的网站密钥停用域名验证后,Google Cloud Armor 会验证该域名。

    REST 和命令行

    如需了解密钥类型和集成类型的 API 参考信息,请参阅密钥集成类型

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

    • PROJECT_ID:您的 Google Cloud 项目 ID
    • DISPLAY_NAME:密钥的显示名
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • WAF_FEATURE:WAF 功能的名称。 指定 challenge-page
    • DOMAINS(仅适用于网站和 WAF):网站可用于使用此密钥的网域或子网域。以英文逗号分隔列表的形式指定多个网域。可选:指定 --allow-all-domains 可停用网域验证。

      当您对验证页面的网站密钥停用域名验证后,Google Cloud Armor 会验证该域名。

    • TYPE_OF_INTEGRATION(仅适用于网站和 WAF):指定 INVISIBLE

    HTTP 方法和网址:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    请求 JSON 正文:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
    "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    
    

    如需发送请求,请选择以下方式之一:

    curl

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    $cred = gcloud auth application-default 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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
        "integrationType": "INVISIBLE",
    
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "CHALLENGE_PAGE"
    
      }
    }
    
    

  2. 配置 Google Cloud Armor 安全政策。如需了解如何在安全政策中使用 reCAPTCHA 质询页网站密钥,请参阅配置聊天机器人管理规则

实现 reCAPTCHA 操作令牌

您必须在网页上运行 reCAPTCHA Enterprise 才能生成操作令牌。reCAPTCHA Enterprise 生成操作令牌后,您可以在需要保护任何用户操作(例如结算)的情况下将操作令牌附加到预定义的请求标头。默认情况下,操作令牌的有效期为 30 分钟,有效期较短。因此,您必须在操作令牌到期之前将它附加到预定义的请求标头,使得 Google Cloud Armor 可以评估令牌特性。

如需实现 reCAPTCHA 操作令牌,请执行以下操作:

  1. 创建 reCAPTCHA WAF 操作令牌网站密钥。

    控制台

    1. 在控制台中,转到 reCAPTCHA Enterprise 页面。

      转到 reCAPTCHA Enterprise

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

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

    3. 点击创建密钥

    4. 显示名字段中,输入密钥的显示名。
    5. 选择平台类型下拉菜单中,选择网站

      系统会显示网域列表部分。

    6. 输入您的网站的域名:

      1. 网域列表部分中,点击添加网域

      2. 网域字段中,输入您的域名。
      3. 可选:要添加其他网域,请点击添加网域,然后在网域字段中输入其他网域的名称。 您最多可以添加 250 个网域。

        对于网站,reCAPTCHA 网站密钥对您指定的网域和子网域具有唯一性。如果您从多个网域传送您的网站,则可以指定多个网域。如果您指定了网域(例如 examplepetstore.com),则无需指定其子网域(例如 subdomain.examplepetstore.com)。

    7. 展开 Web 应用防火墙 (WAF)、网域验证、AMP 网页和验证部分。
    8. 开启 Web 应用防火墙 (WAF) 切换开关。
    9. 功能下拉菜单中选择操作令牌

    10. 可选:开启停用域名验证

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    11. 可选:开启使用复选框验证

    12. 点击创建密钥
    13. 新创建的密钥会列在 reCAPTCHA 密钥页面上。

    gcloud

    如需创建 WAF 网站密钥,请使用 gcloud recaptcha keys create 命令:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    请提供以下值:

    • DISPLAY_NAME:密钥的名称。通常是网站名称。
    • WAF_FEATURE:WAF 功能的名称。 指定 action-token
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • INTEGRATION_TYPE:集成类型。 指定 SCORECHECKBOX
    • DOMAIN_NAME:获准使用相应密钥的网站的网域或子网域。以逗号分隔列表的形式指定多个网域。 可选:指定 --allow-all-domains 可停用网域验证。

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    REST 和命令行

    如需了解密钥类型和集成类型的 API 参考信息,请参阅密钥集成类型

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

    • PROJECT_ID:您的 Google Cloud 项目 ID
    • DISPLAY_NAME:密钥的显示名
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • WAF_FEATURE:WAF 功能的名称。 指定 action-token
    • DOMAINS(仅适用于网站和 WAF):网站可用于使用此密钥的网域或子网域。以英文逗号分隔列表的形式指定多个网域。可选:指定 --allow-all-domains 可停用网域验证。

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    • TYPE_OF_INTEGRATION(仅适用于网站和 WAF): 指定 SCORECHECKBOX

    HTTP 方法和网址:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    请求 JSON 正文:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
    "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    
    

    如需发送请求,请选择以下方式之一:

    curl

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    $cred = gcloud auth application-default 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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
       "integrationType": "SCORE",
    
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "ACTION_TOKEN"
    
      }
    }
    
    

  2. 在网页上安装操作令牌网站密钥。如需查看说明,请参阅与您的操作令牌网站密钥的集成类型对应的文档。

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

       X-Recaptcha-Token:value-of-your-action-token
    

    您可以使用 XHR、Ajax 或 Fetch API 等语言将令牌附加到预定义的请求标头上。

    以下示例脚本展示了如何使用 JavaScript + XHR 保护执行操作并将令牌附加到预定义的请求标头:

       <script src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_SITE_KEY"></script>
    
       <script>
    
        function onSuccess(action_token) {
          const xhr = new XMLHttpRequest();
          xhr.open('GET','YOUR_URL', false);
          // Attach the action-token to the predefined request header
          xhr.setRequestHeader("X-Recaptcha-Token", action_token);
          xhr.send(null);
        }
    
        function onError(reason) {
          alert('Response promise rejected: ' + reason);
        }
    
        grecaptcha.enterprise.ready(function () {
          document.getElementById("execute-button").onclick = () => {
            grecaptcha.enterprise.execute('ACTION_TOKEN_SITE_KEY', {
            }).then(onSuccess, onError);
          };
        });
       </script>
    
     ```
    
  4. 配置 Google Cloud Armor 安全政策。如需了解如何将 reCAPTCHA 操作令牌网站密钥与安全政策配合使用,请参阅配置聊天机器人管理规则

实现 reCAPTCHA 会话令牌

在评估后,reCAPTCHA JavaScript 会在最终用户的浏览器上将 reCAPTCHA 会话令牌设置为 Cookie。只要 reCAPTCHA JavaScript 保持活跃状态,最终用户的浏览器就会附加该 Cookie 并刷新该 Cookie。

如需以 Cookie 形式提供会话令牌,请在至少其中一个满足以下要求的网页上安装基于 reCAPTCHA 得分的网站密钥:

  • 网页必须是在需要保护的页面前面最终用户浏览的页面。例如,如果您想保护结帐页面,请在首页或产品页面上安装基于 reCAPTCHA 得分的网站密钥。
  • 网页受 Google Cloud Armor 安全政策保护。

您可以使用此 Cookie 保护在特定网域中用户的后续请求和页面加载。会话令牌的有效期默认为 30 分钟。但是,如果用户留在实现会话令牌的页面上,reCAPTCHA Enterprise 会定期刷新会话令牌以防止它过期。

在需要受 reCAPTCHA Enterprise 保护的每个页面上安装会话令牌。建议在每个页面上安装 reCAPTCHA Enterprise,并使用 Google Cloud Armor 规则强制实施对所有页面(最终用户浏览的第一页除外)的访问权限。

下面是一个 reCAPTCHA 会话令牌示例:

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

如需实现 reCAPTCHA 会话令牌,请执行以下操作:

  1. 创建 reCAPTCHA WAF 会话令牌网站密钥。

    控制台

    1. 在控制台中,转到 reCAPTCHA Enterprise 页面。

      转到 reCAPTCHA Enterprise

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

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

    3. 点击创建密钥

    4. 显示名字段中,输入密钥的显示名。
    5. 选择平台类型下拉菜单中,选择网站

      系统会显示网域列表部分。

    6. 输入您的网站的域名:

      1. 网域列表部分中,点击添加网域

      2. 网域字段中,输入您的域名。
      3. 可选:要添加其他网域,请点击添加网域,然后在网域字段中输入其他网域的名称。 您最多可以添加 250 个网域。

        对于网站,reCAPTCHA 网站密钥对您指定的网域和子网域具有唯一性。如果您从多个网域传送您的网站,则可以指定多个网域。如果您指定了网域(例如 examplepetstore.com),则无需指定其子网域(例如 subdomain.examplepetstore.com)。

    7. 展开 Web 应用防火墙 (WAF)、网域验证、AMP 网页和验证部分。
    8. 开启 Web 应用防火墙 (WAF) 切换开关。
    9. 功能下拉菜单中选择会话令牌

    10. 可选:开启停用域名验证

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    11. 点击创建密钥
    12. 新创建的密钥会列在 reCAPTCHA 密钥页面上。

    gcloud

    如需创建 WAF 网站密钥,请使用 gcloud recaptcha keys create 命令:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    请提供以下值:

    • DISPLAY_NAME:密钥的名称。通常是网站名称。
    • WAF_FEATURE:WAF 功能的名称。 指定 session-token
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • INTEGRATION_TYPE:集成类型。 指定 SCORE
    • DOMAIN_NAME:获准使用相应密钥的网站的网域或子网域。以逗号分隔列表的形式指定多个网域。 可选:指定 --allow-all-domains 可停用网域验证。

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    REST 和命令行

    如需了解密钥类型和集成类型的 API 参考信息,请参阅密钥集成类型

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

    • PROJECT_ID:您的 Google Cloud 项目 ID
    • DISPLAY_NAME:密钥的显示名
    • WAF_SERVICE:WAF 服务提供商的名称。为 Google Cloud Armor 指定 CA
    • WAF_FEATURE:WAF 功能的名称。 指定 session-token
    • DOMAINS(仅适用于网站和 WAF):网站可用于使用此密钥的网域或子网域。以英文逗号分隔列表的形式指定多个网域。可选:指定 --allow-all-domains 可停用网域验证。

      停用网域验证是一种安全风险,因为该网站没有限制,因此任何人都可以访问和使用 reCAPTCHA 密钥。

    • TYPE_OF_INTEGRATION(仅适用于网站和 WAF):指定 SCORE

    HTTP 方法和网址:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    请求 JSON 正文:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
    "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    
    

    如需发送请求,请选择以下方式之一:

    curl

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

    将请求正文保存在名为 request.json 的文件中,然后执行以下命令:

    $cred = gcloud auth application-default 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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
       "integrationType": "SCORE",
    
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "SESSION_TOKEN"
    
      }
    }
    
    

  2. 将会话令牌网站密钥和 waf=session 添加到 reCAPTCHA JavaScript。

    以下示例脚本展示了如何在网页上实现会话令牌:

      <!DOCTYPE html>
      <html lang="en">
      <head>
       <meta charset="UTF-8">
       <title>reCAPTCHA WAF Session Token</title>
       <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_SITE_KEY&waf=session" async defer></script>
      </head>
    </html>
    
  3. 配置 Google Cloud Armor 安全政策。如需了解如何将 reCAPTCHA 会话令牌网站密钥与安全政策配合使用,请参阅配置聊天机器人管理规则

在一款应用中使用多项功能的示例

您可以在一款应用中使用一个或多个 reCAPTCHA Enterprise for WAF 功能。

示例 1:使用 reCAPTCHA 会话令牌和 reCAPTCHA 质询页面

您可以在用户可能会访问的页面(例如登录页面)中添加 reCAPTCHA 会话令牌,以便定期刷新 Cookie。配置 Google Cloud Armor 安全政策规则,以在分数较低时将请求重定向到 reCAPTCHA 质询页面。

下图显示了使用 reCAPTCHA 会话令牌和 reCAPTCHA 质询页面功能的工作流程:

示例 2:使用 reCAPTCHA 操作令牌和 reCAPTCHA 质询页面

您可以添加 reCAPTCHA 操作令牌以保护用户操作,例如结算。配置 Google Cloud Armor 安全政策规则,在以下任一情况下将请求重定向到 reCAPTCHA 质询页面:

  • 得分很低。
  • 操作令牌的 action_name 特性与受保护的用户操作不匹配。

下图显示了使用 reCAPTCHA 操作令牌和 reCAPTCHA 质询页面功能的工作流:

以下示例脚本展示了如何使用 reCAPTCHA 操作令牌并重定向到将操作令牌作为标头附加的 reCAPTCHA 质询页面:

   <script src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_SITE_KEY"></script>
    <script>
     function onSuccess(token) {
       const xhr = new XMLHttpRequest();
       xhr.open('GET','http://www.abc.com/checkout', false);
       xhr.setRequestHeader("X-Recaptcha-Token", token);
       xhr.onreadystatechange = function() {
         // Make sure that the request is finished and response is ready with 200
         if (this.readyState == 4 && this.status == 200) {
           // Display the response, it could be a reCAPTCHA challenge
           // page based on your Google Cloud Armor security rule settings.
            document.open();
            document.write(xhr.responseText);
            document.close();

         }
       };
       xhr.send(null);
     }

     grecaptcha.enterprise.ready(function () {
       document.getElementById("execute-button").onclick = () => {
         grecaptcha.enterprise.execute('ACTION_TOKEN_SITE_KEY', {
         }).then(onSuccess, onError);
       };
     });
    </script>

后续步骤