在应用服务器上设置 reCAPTCHA Express

当无法在客户端集成 reCAPTCHA JavaScript 或移动 SDK 时，可以在应用服务器上设置 reCAPTCHA Express，例如，用于保护 API 端点。

reCAPTCHA Express 是一项功能，可让您在没有客户端集成或客户端信号的情况下创建评估。reCAPTCHA Express 仅使用后端信号来生成 reCAPTCHA 风险得分。您可以根据此风险得分来决定是否处理相应请求、是否重定向到验证页面，或者是否记录该请求以供日后分析。

准备工作

1. 在 Google Cloud 控制台的项目选择器页面上，选择或创建 Google Cloud 项目。

   选择或创建项目所需的角色

   • 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
   • 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予角色。

   转到“项目选择器”

   记录您的 Google Cloud 项目 ID 以供日后使用。

2. 验证是否已为您的 Google Cloud 项目启用结算功能。

3. 启用 reCAPTCHA Enterprise API。

   启用 API 所需的角色

   如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

   启用 API

4. 创建用于身份验证的 API 密钥：

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

      转到“凭据”页面

   2. 点击 创建凭据，然后选择 API 密钥。

   3. 记录 API 密钥以备后用。

创建 reCAPTCHA 快速密钥

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

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

2. gcloud

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

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

   • INTEGRATION_TYPE：集成类型。 指定 score。
   • DISPLAY_NAME：密钥的名称。通常是网站名称。

   执行 gcloud recaptcha keys create 命令：

   Linux、macOS 或 Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME

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

   REST

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

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

   • INTEGRATION_TYPE：集成类型。 指定 score。
   • DISPLAY_NAME：密钥的名称。通常是网站名称。
   • DEFAULT_SCORE_THRESHOLD：对于基于政策的验证密钥，如果未定义自定义分数阈值，此参数将定义该密钥的通用验证阈值。此功能处于预览版阶段。
   • ACTION_SCORE_THRESHOLDS：对于基于政策的质询密钥，此参数用于指定操作以及介于 0.0 和 1.0 之间的相应阈值分数。例如 login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。此功能处于预览版阶段。
     注意：评估中仅返回在完成所有挑战后计算出的最终得分。将 reCAPTCHA 计算的初始得分与阈值进行比较。

   HTTP 方法和网址：

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

   请求 JSON 正文：

   
   {
     "displayName": "DISPLAY_NAME",
     "expressSettings": {}
   }
   
   

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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "expressSettings": {
   }
   }
   
   

记录您的快捷键以备稍后使用。

创建评估

如需从应用服务器向 reCAPTCHA 发出请求，请使用 projects.assessments.create 方法创建评估。

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

• API_KEY：您为身份验证创建的 API 密钥。
• EXPRESS_KEY：您为应用创建的 reCAPTCHA Express 密钥。
• USER_IP_ADDRESS：用户设备在与此事件相关的请求中的 IP 地址。
• HEADER_INFO：可选。客户端发送到应用服务器的 HTTP 标头。这是一个字符串数组，包含采用 `[key:value]` 格式的请求标头。例如，`[key:value, key:value,...]`。建议您按要求的顺序尽可能多地分享标题。确保同一会话中所有请求的标头顺序保持一致。
• JA3_FINGERPRINT：可选。JA3 是 TLS 客户端 Hello 数据包的某些字段的 MD5 指纹。如需了解详情，请参阅 JA3 - 一种用于分析 SSL/TLS 客户端的方法。
• URI_NAME：可选。用户正在访问的 URI。
• USER_AGENT：可选。用户设备在与相应事件相关的请求中提供的用户代理。
• ACCOUNT_ID：可选。用户账号的唯一永久性标识符，例如经过哈希处理的账号名称。

HTTP 方法和网址：

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

请求 JSON 正文：

{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

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

curl

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

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

解释得分

reCAPTCHA Express 仅返回两个得分：0.3 和 0.7。0.3 表示用户互动风险较高，可能具有欺诈性；0.7 表示用户互动风险较低，可能具有合法性。

如果信号不足，reCAPTCHA Express 默认返回 0.7。

后续步骤

• 了解如何解读风险得分。
• 了解如何在 WAF 层使用 reCAPTCHA express。