使用通用密钥设置政策引擎

预览

此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。 正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本文档介绍了如何使用通用密钥在网站上配置政策引擎。通用密钥是一种新的 Google Cloud Fraud Defense 密钥，支持在 Policy Engine 中创建规则。

借助 Policy Engine，Fraud Defense 可以根据您配置的自定义政策规则确定性地触发 CAPTCHA 验证。这些规则可能会根据风险得分、IP 地址、用户代理、ASN 或经过验证的机器人（AI 代理）身份来决定何时显示欺诈防御质询。

Fraud Defense 政策引擎配置提供两项主要功能：

• AutoExecute 集成 (protected_endpoint_group)：通过自动检查传出的异步网络请求并将 reCAPTCHA 令牌附加到这些请求，简化了前端 JavaScript 集成，因此您只需在前端添加一个脚本标记。
• 质询政策 (challenge_rule_groups)：确定是否针对不同的用户操作显示质询，并使用基于自定义 CEL 的规则配置关联的质询难度级别（USABILITY、BALANCE、SECURITY）。

准备工作

1. 为 reCAPTCHA 准备环境。

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

   Fraud Defense 要求在项目上关联并启用结算功能才能使用 Policy Engine。您可以使用信用卡或现有的 Google Cloud 项目结算 ID 来启用结算功能。如果您需要结算方面的帮助，请与 Cloud Billing 支持团队联系。

创建通用密钥

根据您的首选界面，选择相应选项来创建通用密钥：

控制台

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

   前往 reCAPTCHA

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

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

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

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

gcloud

如需使用 Google Cloud CLI 创建通用密钥，请使用带有 --universal 标志的 gcloud recaptcha keys create 命令：

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

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

REST API

如需使用 REST API 创建通用密钥，请使用 projects.keys.create 方法并指定 universalSettings：

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

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

替换以下内容：

• PROJECT_ID：您的 Google Cloud 项目 ID
• DISPLAY_NAME：密钥的显示名，通常是您的网站名称

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

为政策引擎配置网域

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

根据您的首选界面，选择相应的选项来为您的通用密钥配置允许的网域：

控制台

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

   前往 Fraud Defense

2. 检查项目名称是否显示在页面顶部的资源选择器中。

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

3. 点击 reCAPTCHA 密钥标签页。

4. 找到要配置的通用密钥，然后点击该密钥。

5. 在密钥详情页面上，点击修改密钥。

6. 找到密钥使用情况设置部分。

   为了保护您的网域和子网域的 reCAPTCHA 密钥，请确保关闭停用域名验证切换开关。

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

   输入您的网站的域名：

   1. 在网域列表部分中，点击添加网域。
   2. 在网域字段中，输入您的域名。
   3. 可选：如需添加其他网域，请点击添加网域，然后在网域字段中输入其他网域的名称。您最多可以添加 250 个网域。

7. 点击保存更改。

注意： 如需在超过 250 个网域上使用政策，请点击停用网域验证切换开关。如果停用域名验证，Fraud Defense 会忽略域名列表，您必须自行执行域名验证，即检查您所创建评估中的 tokenProperties.hostname 字段。

gcloud

如需使用 Google Cloud CLI 更新通用密钥的允许网域，请使用 gcloud alpha recaptcha policies update 命令，并在政策配置文件（例如 POLICY.yaml）中指定网域：

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

注意： gcloud alpha recaptcha policies update 命令会更新整个政策。任何现有的 protected_endpoint_group 或 challenge_rule_groups 都必须包含在 POLICY.yaml 文件中，以免被删除。

POLICY.yaml 文件必须在 clientSettings 下指定允许的网域：

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

或者，如需允许所有网域并停用域名验证，请在 POLICY.yaml 文件中将 allowAllDomains 设置为 true：

clientSettings:
  allowAllDomains: true

替换以下内容：

• KEY_ID：您的通用密钥的 ID 或完整资源名称
• DOMAIN_NAME_1、DOMAIN_NAME_2：获准使用该密钥的网站的域名

注意： 当 allowAllDomains 设置为 true 时，Fraud Defense 会忽略网域列表，您必须通过检查所创建评估中的 tokenProperties.hostname 字段自行执行域名验证。

REST API

如需使用 REST API 更新通用密钥的允许网域，请使用 projects.keys.updatePolicy 方法。

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

• PROJECT_ID：您的 Google Cloud 项目 ID
• KEY_ID：您的通用密钥的 ID
• DOMAIN_NAME_1、DOMAIN_NAME_2：获准使用该密钥的网站的域名

HTTP 方法和网址：

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

请求 JSON 正文：

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

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

curl -X PATCH \
     -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/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

如果请求成功，则返回更新后的政策配置。

注意： 如需对超过 250 个网域使用政策，请在请求正文中将 allowAllDomains 设置为 true。如果 allowAllDomains 设置为 true，Fraud Defense 会忽略网域列表，您必须自行执行域名验证，即检查您所创建评估中的 tokenProperties.hostname 字段。

后续步骤

• 在网页上安装通用密钥。