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. 在 reCAPTCHA 密钥 列表中，找到要复制的密钥，然后点击 复制到剪贴板。
- 如需使用 REST API 复制现有密钥的 ID，请调用 projects.keys.list 方法。
- 如需使用 gcloud CLI 复制现有密钥的 ID，请运行 gcloud recaptcha keys list 命令。
规划 Fraud Defense 集成，确定要保护的用户操作（例如 login、signup 或 password_reset）以及网站上触发这些操作的网页。如果您使用 AutoExecute 配置，请确保这些操作与 protected_endpoint_group 中指定的操作名称一致。
将 Fraud Defense 集成到您的网页中。我们建议您使用 Fraud Defense AutoExecute 配置。如需了解一般设置说明，请参阅在网站上安装通用密钥。

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 搜索助理和合作伙伴内容抓取工具）的列表。

定义了以下其他非原始类型。如需查看完整的值列表，请参阅 Bot。

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 代理显示验证

根据复杂条件显示验证

后续步骤

配置验证政策