将 reCAPTCHA for WAF 与 Fastly 集成

action-token

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

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

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

   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 服务提供商的名称。 为 Fastly 指定 fastly。

   执行 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 服务提供商的名称。 为 Fastly 指定 fastly。

   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": "fastly",
   
     "wafFeature": "ACTION_TOKEN"
     
   
   }
   }
   
   

   记录您的操作令牌密钥以供日后使用。

2. 在网页上集成 reCAPTCHA JavaScript，并使用您创建的操作令牌密钥。如需查看相关说明，请参阅与您的操作令牌密钥的集成类型对应的文档。
   • 对于 SCORE 集成类型，请参阅将基于得分的密钥与前端集成。
   • 对于 CHECKBOX 集成类型，请参阅在前端呈现 reCAPTCHA 微件。
3. 从 reCAPTCHA 收到令牌后，请将令牌附加到预定义的请求标头，格式如下：

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

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

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

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

session-token

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

如需以 Cookie 形式提供会话令牌，请在至少其中一个网页上安装会话令牌密钥，最终用户会在浏览需要保护的网页之前浏览该网页。例如，如果您想保护结账页面，请在首页或产品页面上安装会话令牌密钥。

如需了解如何在网页上安装会话令牌密钥，请参阅将基于得分的密钥与前端集成。

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

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

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

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

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

   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 服务提供商的名称。 为 Fastly 指定 fastly。

   执行 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 服务提供商的名称。 为 Fastly 指定 fastly。

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

challenge-page

当您实现 reCAPTCHA 验证页面时，reCAPTCHA 会重定向到插页式广告页面，并在该页面中确定是否有必要向用户显示人机识别系统质询。因此，并非所有用户都可以看到人机识别系统质询。

如需实现 reCAPTCHA 验证页面，请执行以下操作：

1. 为您的网站创建挑战页面密钥。 <0x0A

   gcloud

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

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

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

   执行 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 服务提供商的名称。 为 Fastly 指定 fastly。

   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": "fastly",
   
     "wafFeature": "CHALLENGE_PAGE"
     
   
   }
   }
   
   

   记录您的质询页面密钥以备后用。

2. 如需将用户重定向到 reCAPTCHA 验证页面并接收 reCAPTCHA 令牌，请在受保护的页面上创建具有 redirect 操作的防火墙政策。

快速

如需实现 reCAPTCHA Express，请创建 Express 密钥。

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud

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

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

   • DISPLAY_NAME：密钥的名称。通常是网站名称。
   • WAF_SERVICE：WAF 服务提供商的名称。 为 Fastly 指定 fastly。

   执行 gcloud recaptcha keys create 命令：

   Linux、macOS 或 Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME  \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME  `
   --waf-service=WAF_SERVICE

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME  ^
   --waf-service=WAF_SERVICE

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

   REST

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

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

   • DISPLAY_NAME：密钥的名称。通常是网站名称。
   • WAF_SERVICE：WAF 服务提供商的名称。 为 Fastly 指定 fastly。

   HTTP 方法和网址：

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

   请求 JSON 正文：

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
     
   }
   

   如需发送请求，请选择以下方式之一：

   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,
   
   },
   "wafSettings": {
     "wafService": "fastly",
   
     
   
   }
   }
   
   

   记录您的快捷键以供日后使用。