在应用服务器上设置 reCAPTCHA Express

本文档介绍了如何在无法集成 reCAPTCHA JavaScript 或移动 SDK 的环境（例如保护 API 端点）中，在应用服务器上设置 reCAPTCHA Express。

reCAPTCHA 极速版是一项功能，可让您在不使用客户端功能的情况下创建评估。reCAPTCHA 极速版仅使用后端信号生成 reCAPTCHA 风险得分。您可以根据此风险评分来决定是处理请求、重定向到验证页面，还是将其记录下来以供日后分析。

准备工作

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

   记下您的 Google Cloud 项目 ID，以备日后使用。

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the reCAPTCHA Enterprise API.

   Enable the API

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

   1. 在 Google Cloud 控制台中，转到凭据页面。

      转到“凭据”页面

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

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

创建 reCAPTCHA 极速验证密钥

如需实现 reCAPTCHA 极速验证，请创建 reCAPTCHA 极速验证密钥。

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：密钥的名称。通常是网站名称。

   执行 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 参考文档信息，请参阅密钥和集成类型。

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

   • DISPLAY_NAME：密钥的名称。通常是网站名称。

   HTTP 方法和网址：

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

   请求 JSON 正文：

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

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

   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,
   "expressSettings": {
   }
   }
   
   

记录您的极速密钥，以备日后使用。

创建评估

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

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

• API_KEY：您为身份验证创建的 API 密钥。
• EXPRESS_KEY：您为应用创建的 reCAPTCHA 极速验证密钥。
• 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 -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"

$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/",
    "firewallPolicyEvaluation": false,
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

解释得分

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

如果缺少信号，则 reCAPTCHA 极速版默认返回 0.7。

后续步骤

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