Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置验证政策

本文档介绍了如何通过现有的 Google Cloud Fraud Defense 集成配置验证政策。

通过验证政策，您可以根据自定义规则有选择地触发人机识别系统验证。这些规则会根据风险评分、IP 地址、用户代理、ASN、地理区域或经过验证的机器人（AI 智能体）身份，决定何时显示 Fraud Defense 验证。

您可以将验证政策与以下推荐功能搭配使用：

AutoExecute 配置：简化客户端应用的 JavaScript 集成。
验证：在验证规则要求时触发用户验证。Fraud Defense 支持以下验证类型：
- 视觉验证：要求用户根据提示选择图片。默认情况下，如果配置规则时选择了验证选项，系统会选择视觉验证。
- 音频验证：要求用户识别语音提示，作为无障碍替代方案。
- 二维码验证：要求用户使用移动设备扫描二维码来完成验证。您的通用密钥必须在许可清单中，才能使用此功能。如需将您的通用密钥添加到许可清单，请发送电子邮件至 fraud-defense@google.com 与 Fraud Defense 团队联系，并提供您的通用密钥。

准备工作

为 Google Cloud Fraud Defense 准备好环境。
验证是否已为您的 Google Cloud 项目启用结算功能。您可以使用信用卡或现有 Google Cloud 项目结算 ID 来启用结算功能。如果您需要结算方面的帮助，请联系 Cloud Billing 支持团队。
为您的项目创建或标识通用密钥。如需创建密钥，请参阅创建通用密钥。或者，您也可以通过完成以下任一步骤来复制现有通用密钥的 ID：
- 如需从 Google Cloud 控制台复制现有密钥的 ID，请执行以下操作：
  1. 在 Google Cloud 控制台中，前往 Google Cloud Fraud Defense 页面。
    
    前往 Fraud Defense
  2. 在密钥列表中，找到要复制的密钥，然后点击 复制到剪贴板。
- 如需使用 REST API 复制现有密钥的 ID，请调用 projects.keys.list 方法。
- 如需使用 gcloud CLI 复制现有密钥的 ID，请运行 gcloud recaptcha keys list 命令。
通过确定您要保护的用户操作（例如 login、signup 或 password_reset）以及您网站上的哪些页面会触发这些操作，来规划 Fraud Defense 集成。如果您使用 AutoExecute 配置，请确保这些操作与 protected_endpoint_group 中指定的操作名称一致。
将 Fraud Defense 集成到您的网页中。我们建议您使用 Fraud Defense AutoExecute 配置。如需了解一般设置说明，请参阅在网站上安装 Universal 密钥。

Fraud Defense 政策配置概览

通过 Fraud Defense 政策配置，您可以自定义 Fraud Defense 防护功能的行为。您可以使用 challenge_rule_groups 部分配置验证政策。

您可以使用 Google Cloud 控制台、gcloud CLI 或 reCAPTCHA Enterprise REST API 查看和更新政策配置。

控制台

如需在 Google Cloud 控制台中查看或更新政策配置，请执行以下操作：

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

前往 Fraud Defense
确保在资源选择器中选择您的项目。
在 reCAPTCHA 密钥表中，点击要为其配置验证码政策的密钥的名称。
在密钥详情页面上，前往政策标签页。
在规则组部分中，您可以查看、添加或修改质询规则和条件表达式。
点击保存。

gcloud

如需更新密钥的政策配置，请运行 gcloud alpha recaptcha policies update 命令：

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

如需查看密钥的当前政策配置，请运行 gcloud alpha recaptcha policies describe 命令：

gcloud alpha recaptcha policies describe --key=KEY_ID

REST API

如需更新密钥的政策配置，请调用 projects.keys.updatePolicy 方法：

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

如需查看密钥的当前政策配置，请调用 projects.keys.getPolicy 方法：

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

政策配置对 Google Cloud CLI 使用 YAML 格式，对 REST API 使用 JSON 格式。如需查看 challenge_rule_groups 部分的完整架构，请参阅配置质询政策。

如需查看不同用例的示例，请参阅验证规则配置示例。

配置验证政策

您可以在 Fraud Defense 政策配置的 challenge_rule_groups 部分中配置验证政策。如果您已有包含 client_settings（包括网域信息）的政策，则可以更新该政策，以包含质询政策规则。

challenge_rule_groups 部分具有以下结构：

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

在每条质询规则中，condition 字段均为可选字段。如果未指定 condition 或其为空，则规则会无条件应用。此外，challenge 和 no_challenge 字段是互斥的，每条规则中必须恰好存在其中一个字段。

规则评估顺序

系统会按从上到下的顺序依次评估规则组及其内部规则。会应用第一个匹配的规则。当没有规则组和规则与互动匹配时，评估会默认使用标准评估，不显示验证码，但会为请求生成风险评分。

验证难度级别

您可以在触发挑战时指定难度级别。如需查看有效难度值的完整列表，请参阅 ChallengeSecurityPreference API 参考文档。

条件语法

condition 字段是一个可选字符串，格式为通用表达式语言 (CEL) 表达式。如果 condition 未指定或为空，则规则会无条件应用。CEL 提供标准的 C 语言式运算符，包括关系运算符（<、<=、>、>=、==、!=）、算术运算符（+、-、/、*、%）、逻辑运算符（!、&&、||）和容器运算符（[]、in）。CEL 支持常见的基元数据类型（bool、int、uint、double、string）、基本容器类型（lists、messages）和常量（例如 true、1、0.5、"hello" 和 [1, 2, 3]）。

在运行时，可以访问以下 Fraud Defense 变量：

变量	类型	说明
`score`	`double`	Fraud Defense 机器人得分。
`user_ip_address`	`string`	发出请求的用户的 IP 地址（IPv4 或 IPv6）。
`user_agent`	`string`	发出请求的用户代理。
`user_asn`	`int`	发出请求的用户的自治系统编号 (ASN)。省略 `AS` 前缀（例如，使用 `12345` 而不是 `AS12345`）。
`region_code`	`string`	与请求位置关联的 Unicode CLDR 区域代码（基于 ISO 3166-1 alpha-2），例如 `"US"`、`"CA"` 或 `"FR"`。
`verified_bots`	`list(Bot)`	Fraud Defense 已识别且经过验证的自动抓取工具或代理（例如搜索引擎索引器、AI 搜索助理和合作伙伴内容抓取工具）的列表。

定义了以下其他非基元类型。如需查看值的完整列表，请参阅机器人。

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

如需详细了解可能的 name 值，请参阅 Bot API 参考文档。如需详细了解有效的 bot_type 枚举值，请参阅 BotType API 参考文档。

在 Fraud Defense 验证码政策中，您可以使用以下任一变量来生成布尔表达式。例如，score > 0.5、user_ip_address == "192.0.2.1"、region_code == "US" 和 user_asn == 12345 都是有效的条件表达式，其求值结果为布尔值。请注意，由于 user_asn 是整数类型，因此在检查 ASN 时，您必须省略 AS 前缀。

以下函数可在 Fraud Defense 验证码政策条件中使用：

名称	签名	说明
`contains`	`string.contains(string) -> bool`	检查字符串操作数是否包含子字符串。
`startsWith`	`string.startsWith(string) -> bool`	检查字符串操作数是否以指定的前缀开头。
`endsWith`	`string.endsWith(string) -> bool`	检查字符串操作数是否以指定的后缀结尾。
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	返回字符串的大小（码位数量）或列表的大小（元素数量）。

理解函数是内置于 CEL 中的一种宏。可使用以下推导式：

名称	签名	说明	示例
`has`	`has(message.field) -> bool`	检查某个字段是否可用。	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	检查列表 `e` 中的所有元素 `x` 是否都与谓词 `p` 匹配。	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	检查列表 `e` 中的任何元素 `x` 是否与谓词 `p` 匹配。	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	检查列表 `e` 中是否恰好有一个元素 `x` 与谓词 `p` 匹配。	`[1, 2, 2].exists_one(i, i < 2)`

验证规则配置示例

本部分包含有效的验证码规则配置示例。

质询所有得分较低的请求

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

为所有得分较低的请求选择高摩擦验证

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

对得分较低的特定操作提出异议

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

为不同的操作配置不同的规则阈值

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

不向许可清单中的 IP 地址显示验证

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

注意：此规则与 Fraud Defense IP 许可清单功能不同。

不向 IP 地址子网显示验证

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

不向来自特定 ASN 的请求显示验证

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

不向 Google 代理显示验证问题

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

根据复杂条件显示验证问题

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

后续步骤

如需评估 reCAPTCHA 响应令牌，请参阅为网站创建评估。

配置验证政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

Fraud Defense 政策配置概览

控制台

gcloud

REST API

配置验证政策

规则评估顺序

验证难度级别

条件语法

验证规则配置示例

质询所有得分较低的请求

为所有得分较低的请求选择高摩擦验证

对得分较低的特定操作提出异议

为不同的操作配置不同的规则阈值

不向许可清单中的 IP 地址显示验证

不向 IP 地址子网显示验证

不向来自特定 ASN 的请求显示验证

不向 Google 代理显示验证问题

根据复杂条件显示验证问题

后续步骤

配置验证政策