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

预览

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

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

借助政策引擎，Fraud Defense 可以根据您配置的自定义政策规则确定性地触发人机识别系统验证。这些规则可能会根据风险评分、IP 地址、用户代理、ASN 或经过验证的漫游器（AI 智能体）身份，决定何时显示 Fraud Defense 验证。

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

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

准备工作

1. 为 Google Cloud Fraud Defense 准备好环境。

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

   必须有关联且已启用的结算账号，才能使用政策引擎。您可以使用信用卡或现有 Google Cloud 项目结算 ID 来启用结算功能。如果您需要结算方面的帮助，请与 Cloud Billing 支持团队联系。

创建通用密钥

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

控制台

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

   前往 Google Cloud Fraud Defense

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

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

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

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

gcloud

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

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

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

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 密钥对于您指定的网域和子网域是唯一的。如果您通过多个网域提供网站，则可以指定多个网域。如果您指定了某个网域（例如 examplepetstore.com），则无需指定其子网域（例如 subdomain.examplepetstore.com）。

根据您偏好的界面，选择适当的选项来为通用密钥配置允许的网域：

控制台

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

   前往 Fraud Defense

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

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

3. 点击密钥标签页。

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

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 字段。

后续步骤

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