为网站创建 reCAPTCHA 密钥

本页介绍了如何创建 reCAPTCHA 密钥，以验证网页上的用户互动。

reCAPTCHA 密钥表示 reCAPTCHA 如何针对网站进行配置。该配置包含一些重要选项，例如是否显示 CAPTCHA 验证。

准备工作

• 为 Google Cloud Fraud Defense 准备好环境。
• 确保您拥有以下 Identity and Access Management 角色：reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin)。
• 选择最适合您的使用情形的密钥类型。

创建 reCAPTCHA 密钥

您可以为一个 Google Cloud 项目创建的 reCAPTCHA 密钥数量不受限制。最好为每个网站创建一个 reCAPTCHA 密钥。

我们建议为预演环境和生产环境分别创建 reCAPTCHA 密钥。否则，您可能会使用测试环境中的数据污染 reCAPTCHA 风险分析。

创建 reCAPTCHA 密钥的最简单方法是通过 reCAPTCHA 管理控制台进行创建。 或者，您也可以使用 Google Cloud 控制台、reCAPTCHA Enterprise API 或 Google Cloud CLI。

管理控制台

1. 前往 Google Cloud Fraud Defense 管理控制台。

   前往“欺诈防御”管理控制台

2. 在标签字段中，输入一个可用于标识您网站的名称。
3. 如果您想创建基于得分的密钥，请选择基于得分 (v3)。如果您想创建复选框密钥，请选择基于验证方式 (v2)。
4. 如需添加网域，请输入您的域名，然后点击 。

   如需添加其他网域，您可以重复执行此步骤。您最多可以添加 250 个网域。

5. 如果您是 Google Cloud 控制台的新用户，请阅读服务条款，然后选中复选框。
6. 点击提交。

如果您是 Google Cloud 控制台的新用户，系统会为您创建一个 Google Cloud 项目并启用必要的 API，以便您开始使用。如果您已有 Google Cloud 项目，则已为您的项目启用必要的 API，您可以开始使用了。

Cloud 控制台

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

   前往 Google Cloud Fraud Defense

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

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

3. 选择密钥标签页。
4. 点击创建密钥。
5. 在显示名称字段中，输入密钥的显示名称。
6. 对于应用类型，选择 Web。

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

7. 为保护您的网域和子网域的 reCAPTCHA 密钥，请确保停用网域验证切换开关处于关闭状态。

   停用域名验证会带来安全风险，因为这样一来，网站就不受任何限制，任何人都可以访问和使用您的 reCAPTCHA 密钥。

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

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

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

      对于网站，reCAPTCHA 密钥对于您指定的网域和子网域是唯一的。如果您从多个网域传送您的网站，则可以指定多个网域。如果您指定了某个网域（例如 examplepetstore.com），则无需指定其子网域（例如 subdomain.examplepetstore.com）。对网域列表所做的更改最多可能需要 30 分钟才能生效。

      如需在 250 个以上的网域中使用密钥，请点击停用网域验证切换开关。 然后，Google Cloud Fraud Defense 会忽略该网域列表。 您需要自行执行域名验证，即检查您所创建评估中的 tokenProperties.hostname 字段。

9. 根据您要为网站创建的 reCAPTCHA 密钥类型，执行相应操作：

创建基于分数的 reCAPTCHA 密钥

注意：在 Google Cloud 控制台中，创建基于得分的密钥是默认选项。

1. 如果您想允许基于得分的密钥使用 amp-recaptcha-input 组件与 Accelerated Mobile Pages (AMP) 搭配使用，请开启允许将此密钥用于 AMP 网页切换开关。

2. 对于非生产环境，如果您想指定在为密钥创建任何评估时，该密钥应返回的分数，请执行以下操作：

   1. 点击下一步（可选）
   2. 在“其他设置”步骤中，点击您创建此密钥是否仅用于测试目的？切换开关。
   3. 使用设置得分滑块指定介于 0 到 1.0 之间的得分。
3. 点击创建密钥。

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

创建复选框 reCAPTCHA 密钥

我们不建议使用复选框键，因为它们会给用户带来不便，且不会显著提高准确率。

1. 点击下一步（可选）。
2. 在“其他设置”步骤中，开启您是否会使用验证？ 切换。
3. 选择相应的质询安全性选项。

   验证安全性选项可控制提示用户进行二级挑战的可能性，在二级挑战中，将提示用户根据已确定的类别选择图像（例如，选择含摩托车或楼梯的图片）。

   如果您想确保获得最佳欺诈防护，请选择严格。

   如果您选择简单，系统不太可能会提示用户完成视觉挑战。

4. 对于非生产环境，如果您想指定在为密钥创建任何评估时，该密钥应返回的分数，请执行以下操作：

   1. 点击您创建此密钥是否仅用于测试目的？切换开关。
   2. 使用设置得分滑块指定介于 0 到 1.0 之间的得分。
   3. 选择相应的挑战类型选项。
      • 自动有时会弹出挑战。
      • No CAPTCHA 不会显示验证。
      • 不可避开的验证会显示图片，但验证未通过。
   4. 点击创建密钥。

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

创建基于政策的验证 reCAPTCHA 密钥

1. 点击下一步（可选）。
2. 在“其他设置”步骤中，开启您是否会使用验证？ 切换。
3. 选择相应的质询安全性选项。

   验证安全性选项用于定义向用户显示的人机识别系统验证的复杂性和频率。

   如果您想确保获得最佳欺诈防护，请选择严格。

   如果您选择简单，系统会减少人机识别系统验证的次数，并降低验证的复杂程度，从而减少用户遇到验证提示的可能性。

4. 对于非生产环境，如果您想指定在为密钥创建任何评估时返回的分数，请执行以下操作：

   1. 点击您创建此密钥是否仅用于测试目的？切换开关。
   2. 使用设置得分滑块指定介于 0 到 1.0 之间的得分。
5. 选择触发人机识别系统验证题目的分数阈值，该阈值适用于所有操作。
6. 点击创建密钥。

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

gcloud

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

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

• INTEGRATION_TYPE：集成类型。 根据密钥类型，指定以下值：
  • score，用于基于得分的密钥。
  • checkbox 用于复选框键。
  • policy-based-challenge，用于基于政策的验证密钥。
  注意：我们不建议使用 CHECKBOX，因为这会增加用户不便，且不会显著提高准确率。 如需了解详情，请参阅常见问题解答。
• DISPLAY_NAME：密钥的名称。通常是网站名称。
• DOMAIN_NAME：允许使用相应密钥的网站的网域或子网域。

  以英文逗号分隔列表的形式指定多个网域。

  如需在 250 个以上的网域中使用密钥，请指定 --allow-all-domains 以停用域名验证。 然后，Google Cloud Fraud Defense 会忽略该网域列表。 您需要自行执行域名验证，即检查您所创建评估中的 tokenProperties.hostname 字段。

  停用域名验证会带来安全风险，因为这样一来，网站就不受任何限制，任何人都可以访问和使用您的 reCAPTCHA 密钥。

  注意： reCAPTCHA 密钥对于您指定的网域和子网域是唯一的。如果您通过多个网域提供网站，则可以指定多个网域。如果您指定了某个网域（例如 examplepetstore.com），则无需指定其子网域（例如 subdomain.examplepetstore.com）。对网域列表所做的更改可能需要长达 30 分钟的时间才会生效。
• DEFAULT_SCORE_THRESHOLD：对于基于政策的验证密钥，此参数用于在未定义自定义分数阈值时，为密钥定义通用验证阈值。
• ACTION_SCORE_THRESHOLDS：对于基于政策的质询密钥，此参数用于指定操作以及介于 0.0 和 1.0 之间的相应阈值分数。例如 login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。
  注意：评估中仅返回在完成所有挑战后计算出的最终得分。将 Fraud Defense 计算的初始得分与阈值进行比较。

执行 gcloud recaptcha keys create 命令：

Linux、macOS 或 Cloud Shell

gcloud recaptcha keys create \
        --web \
        --display-name=DISPLAY_NAME  \
        --integration-type=INTEGRATION_TYPE \
        --domains=DOMAIN_NAME \

Windows (PowerShell)

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME `

Windows (cmd.exe)

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME ^

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

REST

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

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

• INTEGRATION_TYPE：集成类型。 根据密钥类型，指定以下值：
  • SCORE，用于基于得分的密钥。
  • CHECKBOX 用于复选框键。
  • POLICY_BASED_CHALLENGE，用于基于政策的验证密钥。
  注意：我们不建议使用 CHECKBOX，因为这会增加用户不便，且不会显著提高准确率。 如需了解详情，请参阅常见问题解答。
• DISPLAY_NAME：密钥的名称。通常是网站名称。
• DOMAIN_NAME：允许使用相应密钥的网站的网域或子网域。

  以英文逗号分隔列表的形式指定多个网域。

  如需在 250 个以上的网域中使用密钥，请指定 --allow-all-domains 以停用域名验证。 然后，Google Cloud Fraud Defense 会忽略该网域列表。 您需要自行执行域名验证，即检查您所创建评估中的 tokenProperties.hostname 字段。

  停用域名验证会带来安全风险，因为这样一来，网站就不受任何限制，任何人都可以访问和使用您的 reCAPTCHA 密钥。

  注意： reCAPTCHA 密钥对于您指定的网域和子网域是唯一的。如果您通过多个网域提供网站，则可以指定多个网域。如果您指定了某个网域（例如 examplepetstore.com），则无需指定其子网域（例如 subdomain.examplepetstore.com）。对网域列表所做的更改可能需要长达 30 分钟的时间才会生效。
• DEFAULT_SCORE_THRESHOLD：对于基于政策的验证密钥，此参数用于在未定义自定义分数阈值时，为密钥定义通用验证阈值。
• ACTION_SCORE_THRESHOLDS：对于基于政策的质询密钥，此参数用于指定操作以及介于 0.0 和 1.0 之间的相应阈值分数。例如 login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'。
  注意：评估中仅返回在完成所有挑战后计算出的最终得分。将 Fraud Defense 计算的初始得分与阈值进行比较。
• 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",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "INTEGRATION_TYPE"
  }
}

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

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/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

注意： 创建 reCAPTCHA 密钥后，您可以对其进行修改或删除。您无法恢复已删除的密钥。此外，您无法将 reCAPTCHA 密钥从一个 Google Cloud 项目迁移到另一个项目。

（可选）查找旧版 reCAPTCHA 密钥

如果您想与未使用 reCAPTCHA Enterprise API 的第三方应用集成，则需要旧密钥。

对于您创建的每个网站密钥，reCAPTCHA 都会创建一个旧版 reCAPTCHA Secret 密钥（旧版 Secret 密钥），您可以将该密钥与第三方应用搭配使用。

注意： 第三方应用或插件通常将此旧版密钥称为私钥或密钥。

如果您需要 reCAPTCHA 传统版密钥的密钥，请将密钥迁移到 reCAPTCHA on Google Cloud，然后找到旧版密钥。

注意： 我们不建议在前端使用旧版密钥，因为该密钥对用户可见，攻击者可能会滥用您的应用。

如需查找旧版密钥，请执行以下操作：

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

   前往 Fraud Defense

2. 选择密钥标签页。

3. 在 reCAPTCHA 密钥部分中，找到您创建的 reCAPTCHA 密钥，然后点击该密钥。

   

4. 在密钥详情页面上，点击集成标签页下的使用旧版密钥。 系统会打开一个对话框，其中包含有关如何使用旧版密钥的说明。

   

后续步骤

• 在网页上安装基于得分的密钥。
• 在网页上安装复选框密钥。
• 在网页上安装基于政策的挑战密钥。