与 Google Cloud Armor for Websites 集成

本文档介绍了如何在网站上将 reCAPTCHA for WAF 与 Google Cloud Armor 集成。

如需完成集成，您必须实现 reCAPTCHA for WAF 的一项或多项功能，并配置 Google Cloud Armor 安全政策。

准备工作

  1. 启用 reCAPTCHA Enterprise API。

    Enable the API

  2. 规划如何实现 reCAPTCHA for WAF 的功能来保护您的网站。

    1. 选择一个或多个 WAF 功能 最适合您的应用场景的解决方案。
    2. 确定您要保护的页面以及 WAF 功能的类型 您希望在这些网页上植入什么广告

实现 reCAPTCHA for WAF 的功能

根据您的要求，您可以使用 在单个应用中集成 reCAPTCHA for WAF。

如果您想使用多项功能，则必须为每项功能分别创建 reCAPTCHA 密钥，并在应用中使用这些密钥。例如，如果您想使用 reCAPTCHA 操作令牌和 reCAPTCHA 质询页面，则必须创建操作令牌密钥和质询页面密钥，并在应用中使用它们。

实现 reCAPTCHA 操作令牌

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

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

  1. 为您的网站创建操作令牌密钥。

    Cloud 控制台

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

      前往 reCAPTCHA

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

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

    3. 点击创建密钥。
    4. 在显示名字段中，输入密钥的显示名。
    5. 根据您要为其创建 WAF 的 reCAPTCHA 密钥的平台，执行适当的操作：
      1. 在选择平台类型菜单中，选择 网站。

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

      2. 输入您的网站的域名：

        1. 在网域列表部分，点击添加网域。
        2. 在网域字段中，输入您的域名。

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

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

      3. 展开 Web 应用防火墙 (WAF)、域名验证、AMP 网页和验证 部分。
      4. 将 Web 应用防火墙 (WAF) 开关切换到开启状态。

      5. 从功能菜单中，选择操作令牌。

      6. 可选：开启使用复选框验证。

      7. 点击创建密钥。

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

    gcloud

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

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

    • DISPLAY_NAME：密钥的名称。通常是网站名称。
    • INTEGRATION_TYPE：集成类型。 指定 score 或 checkbox。
    • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。

      以逗号分隔列表的形式指定多个网域。 可选：指定 --allow-all-domains 来停用域名验证。

      停用域名验证会带来安全风险，因为 因此您的 reCAPTCHA 密钥可供访问和使用 由任何人创建。

    • WAF_FEATURE：WAF 功能的名称。 指定 action-token。
    • WAF_SERVICE：WAF 服务提供商的名称。 为 Google Cloud Armor 指定 CA。

    执行 gcloud recaptcha keys create 命令：

    Linux、macOS 或 Cloud Shell

    gcloud recaptcha keys create \
--web \
--display-name=DISPLAY_NAME  \
--integration-type=INTEGRATION_TYPE \
--domains=DOMAIN_NAME \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    gcloud recaptcha keys create `
--web `
--display-name=DISPLAY_NAME  `
--integration-type=INTEGRATION_TYPE `
--domains=DOMAIN_NAME `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--web ^
--display-name=DISPLAY_NAME  ^
--integration-type=INTEGRATION_TYPE ^
--domains=DOMAIN_NAME ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    响应中包含新创建的 reCAPTCHA 密钥。

    REST

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

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

    • DISPLAY_NAME：密钥的名称。通常是网站名称。
    • INTEGRATION_TYPE：集成类型。 指定 score 或 checkbox。
    • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。

      以逗号分隔列表的形式指定多个网域。 可选：指定 --allow-all-domains 来停用域名验证。

      停用域名验证会带来安全风险，因为 因此您的 reCAPTCHA 密钥可供访问和使用 由任何人创建。

    • 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",
   '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 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 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": "DISPLAY_NAME,

"webSettings": {
  "allowAllDomains": true,
  "allowedDomains": [
    "localhost"
  ],

 "integrationType": "SCORE",


},
"wafSettings": {
  "wafService": "CA",

  "wafFeature": "ACTION_TOKEN"
  

}
}

  2. 在网页上集成 reCAPTCHA JavaScript，并使用您创建的操作令牌密钥。有关说明，请参阅与 您的操作令牌密钥的集成类型。

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

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

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

    以下示例脚本展示了如何保护 execute 操作并附加 使用 JavaScript + XHR 将令牌传递给预定义的请求标头：

      
  <script>
    src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_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_KEY', {
           }).then(onSuccess, onError);
         };
       });
      }
    </script>

实现 reCAPTCHA 会话令牌

在评估后，reCAPTCHA JavaScript 会在最终用户的浏览器上将 reCAPTCHA 会话令牌设置为 Cookie。最终用户的浏览器会将 并刷新该 Cookie reCAPTCHA JavaScript 仍然有效。

要提供会话令牌作为 Cookie，请安装 会话令牌密钥。 以下要求：

  • 网页必须是最终用户在浏览网页之前 需要加以保护例如，如果您想保护结账页， 在住宅中安装会话令牌密钥 页面或产品页面。
  • 网页受 Google Cloud Armor 安全政策保护。

您可以使用此 Cookie 保护最终用户的后续请求和 网页在特定网域上加载。会话令牌的有效期默认为 30 分钟。但是，如果最终用户留在实施 session-token, reCAPTCHA 会定期刷新会话令牌，以防发生会话令牌 避免过期。

在需要受 reCAPTCHA 保护的每个页面上安装会话令牌。我们建议您使用 reCAPTCHA 保护每个网页，并使用 用于对除第一个页面以外的所有页面强制执行访问权限的 Google Cloud Armor 规则 最终用户浏览的网页

下面是一个 reCAPTCHA 会话令牌示例： 
   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

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

  1. 为您的网站创建会话令牌密钥。

    Cloud 控制台

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

      前往 reCAPTCHA

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

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

    3. 点击创建密钥。
    4. 在显示名字段中，输入密钥的显示名。
    5. 根据您要为其创建 WAF 的 reCAPTCHA 密钥的平台，执行适当的操作：
      1. 在选择平台类型菜单中，选择 网站。

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

      2. 输入您的网站的域名：

        1. 在网域列表部分，点击添加网域。
        2. 在网域字段中，输入您的域名。

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

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

      3. 展开 Web 应用防火墙 (WAF)、域名验证、AMP 网页和验证 部分。
      4. 开启 Web 应用防火墙 (WAF) 切换开关。

      5. 从功能菜单中，选择会话令牌。

      6. 可选：开启停用域名验证功能。

        停用域名验证是一项安全风险，因为网站不受限制，因此任何人都可以访问和使用 reCAPTCHA 密钥。

      7. 点击创建密钥。

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

    gcloud

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

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

    • DISPLAY_NAME：密钥的名称。通常是网站名称。
    • INTEGRATION_TYPE：集成类型。 指定 score。
    • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。

      以逗号分隔列表的形式指定多个网域。 可选：指定 --allow-all-domains 来停用域名验证。

      停用域名验证会带来安全风险，因为 因此您的 reCAPTCHA 密钥可供访问和使用 由任何人创建。

    • WAF_FEATURE：WAF 功能的名称。 指定 session-token。
    • WAF_SERVICE：WAF 服务提供商的名称。 为 Google Cloud Armor 指定 CA。

    执行 gcloud recaptcha keys create 命令：

    Linux、macOS 或 Cloud Shell

    gcloud recaptcha keys create \
--web \
--display-name=DISPLAY_NAME  \
--integration-type=INTEGRATION_TYPE \
--domains=DOMAIN_NAME \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

    Windows (PowerShell)

    gcloud recaptcha keys create `
--web `
--display-name=DISPLAY_NAME  `
--integration-type=INTEGRATION_TYPE `
--domains=DOMAIN_NAME `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--web ^
--display-name=DISPLAY_NAME  ^
--integration-type=INTEGRATION_TYPE ^
--domains=DOMAIN_NAME ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

    响应中包含新创建的 reCAPTCHA 密钥。

    REST

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

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

    • DISPLAY_NAME：密钥的名称。通常是网站名称。
    • INTEGRATION_TYPE：集成类型。 指定 score。
    • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。

      以逗号分隔列表的形式指定多个网域。 可选：指定 --allow-all-domains 来停用域名验证。

      停用域名验证会带来安全风险，因为 因此您的 reCAPTCHA 密钥可供访问和使用 由任何人创建。

    • WAF_FEATURE：WAF 功能的名称。 指定 session-token。
    • WAF_SERVICE： WAF 服务提供商。 为 Google Cloud Armor 指定 CA。

    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 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 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": "DISPLAY_NAME,

"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_KEY&waf=session" async defer></script>
 <body></body>
</head>
</html>

实现 reCAPTCHA 质询页面

在您实施 reCAPTCHA 验证页面时，reCAPTCHA 将 重定向到一个插页，并在这里确定是否需要展示 用户进行人机识别系统验证因此，我们可能无法通过人机识别系统验证 对所有用户可见。

如需实现 reCAPTCHA 质询页面，请为您的网站创建质询页面密钥。

Cloud 控制台

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

    前往 reCAPTCHA

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

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

  3. 点击创建密钥。
  4. 在显示名字段中，输入密钥的显示名。
  5. 根据您希望为 WAF 创建 reCAPTCHA 密钥的平台，执行适当的操作：
    1. 在选择平台类型菜单中，选择 网站。
    2. 展开 Web 应用防火墙 (WAF)、域名验证、AMP 网页和验证 部分。
    3. 将 Web 应用防火墙 (WAF) 开关切换到开启状态。

    4. 从功能菜单中选择挑战页面。

    5. 开启停用域名验证。

      针对质询页密钥停用域名验证后，Google Cloud Armor 会验证网域。

    6. 点击创建密钥。

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

gcloud

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

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

  • DISPLAY_NAME：密钥的名称。通常是网站名称。
  • INTEGRATION_TYPE：集成类型。 指定 invisible。
  • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。 指定 --allow-all-domains。
  • WAF_FEATURE：WAF 功能的名称。 指定 challenge-page。
  • WAF_SERVICE： WAF 服务提供商。 为 Google Cloud Armor 指定 CA。

执行 gcloud recaptcha keys create 命令：

Linux、macOS 或 Cloud Shell

gcloud recaptcha keys create \
--web \
--display-name=DISPLAY_NAME  \
--integration-type=INTEGRATION_TYPE \
--domains=DOMAIN_NAME \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

Windows (PowerShell)

gcloud recaptcha keys create `
--web `
--display-name=DISPLAY_NAME  `
--integration-type=INTEGRATION_TYPE `
--domains=DOMAIN_NAME `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

Windows (cmd.exe)

gcloud recaptcha keys create ^
--web ^
--display-name=DISPLAY_NAME  ^
--integration-type=INTEGRATION_TYPE ^
--domains=DOMAIN_NAME ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

响应中包含新创建的 reCAPTCHA 密钥。

REST

如需查看有关密钥类型和集成类型的 API 参考文档信息， 请参阅密钥 和集成类型。

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

  • DISPLAY_NAME：密钥的名称。通常是网站名称。
  • INTEGRATION_TYPE：集成类型。 指定 invisible。
  • DOMAIN_NAME：获准使用该密钥的网站的网域或子网域。 指定 --allow-all-domains。
  • WAF_FEATURE：WAF 功能的名称。 指定 challenge-page。
  • WAF_SERVICE： WAF 服务提供商。 为 Google Cloud Armor 指定 CA。

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 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 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": "DISPLAY_NAME,

"webSettings": {
  "allowAllDomains": true,
  "allowedDomains": [
    "localhost"
  ],

  "integrationType": "INVISIBLE",
 

},
"wafSettings": {
  "wafService": "CA",

  "wafFeature": "CHALLENGE_PAGE"
  

}
}

配置 Google Cloud Armor 安全政策

在实现 reCAPTCHA for WAF 的功能后， 您必须为聊天机器人配置 Google Cloud Armor 安全政策 管理。

如果您实现了 reCAPTCHA 验证页面，则必须执行以下操作： 以下：

  1. 将质询页面键与您的安全政策相关联。
  2. 配置用于重定向请求以进行 reCAPTCHA 评估的安全政策规则。

如果您实现了 reCAPTCHA 操作令牌或会话令牌，则必须配置用于评估 reCAPTCHA 令牌的安全政策规则。

在配置 Google Cloud Armor 安全政策之前，请先了解 Google Cloud Armor 的 reCAPTCHA 令牌属性。

如需了解如何配置 Google Cloud Armor 安全政策以及如何使用 用于 WAF 的 reCAPTCHA 密钥与您的安全政策，请参阅 配置聊天机器人管理规则。

后续步骤