Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

配置验证政策

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

借助验证政策，您可以根据自定义规则有选择地触发人机识别系统验证。这些规则会根据风险得分、IP 地址、用户代理、ASN 或经过验证的机器人（AI 代理）身份来决定何时显示欺诈防御验证。

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

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

准备工作

为 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 政策配置概览

通过欺诈防御政策配置，您可以自定义欺诈防御保护的行为。您可以使用 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

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

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

配置验证政策

您可以在欺诈防御政策配置的 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) 表达式。如果未指定或为空，则该规则无条件适用。conditionCEL 提供标准的类 C 运算符，包括关系运算符（<、<=、>、>=、==、!=）、算术运算符（+、-、/、*、%）、逻辑运算符（!、&&、||）和容器运算符（[]、in）。CEL 支持常见的原始数据类型（bool、int、uint、double、string）、基本容器类型（lists、messages）和常量（例如 true、1、0.5、"hello" 和 [1, 2, 3]）。

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

变量	类型	说明
`score`	`double`	Fraud Defense Bot 得分。
`user_ip_address`	`string`	发出请求的用户的 IP 地址（IPv4 或 IPv6）。
`user_agent`	`string`	发出请求的用户的用户代理。
`user_asn`	`int`	发出请求的用户的自治系统编号 (ASN)。省略 `AS` 前缀（例如，使用 `12345` 而不是 `AS12345`）。
`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 参考文档。

在欺诈防御质询政策中，您可以使用这些变量中的任意一个来生成布尔表达式。例如，score > 0.5、user_ip_address == "192.0.2.1" 和 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 智能体显示质询

根据复杂条件显示挑战

后续步骤

配置验证政策