撞库与暴力破解防护：登录机器人防护

身份认证功能是新功能。防护在您开启之前处于关闭状态。速率限制和有限次数的验证码尝试始终生效。

机器人防护会作用于每次注册、登录和密码重置。它会将每次尝试与六项策略进行比对。每项策略都有一个模式：

模式	说明
已关闭	不检查该策略。
记录	尝试继续。系统会记录一条 `risk_logged` 事件。
验证	用户必须先通过额外验证，尝试才能继续。
封禁	尝试失败，返回 `403 {"error": "attempt_blocked"}`。

配置防护

通过应用身份认证管理 API 中的 protection/ 路径，使用 GET 和 PATCH 读取和修改设置，或在控制台中操作。

{
  "enabled": true,
  "breached_password_check": true,
  "policies": {
    "bots": "block",
    "stuffing": "block",
    "brute": "challenge",
    "disposable": "block",
    "vpn": "challenge",
    "travel": "block"
  }
}

enabled 和 breached_password_check 默认为 false。开启防护后，上述模式即为默认值。

策略

策略	匹配条件
`bots`	客户端上报的机器人分数为 0.8 或以上，或用户代理是已知的无头浏览器或自动化浏览器。
`stuffing`	同一设备或 IP 在 15 分钟内尝试登录 10 个或以上不同账户，或密码是已知的泄露密码。
`brute`	账户出现 5 次或以上失败尝试。错误密码以及错误的邮箱、手机和身份验证器验证码均计入。
`disposable`	注册时使用一次性邮箱域名。
`vpn`	IP 属于 VPN、Tor 或数据中心网络。
`travel`	本次登录与上一次登录相距超过 500 公里，速度超过 1,000 公里/小时，且两次登录间隔在 24 小时内。

vpn 和 travel 策略使用 Didit 的 IP 分析。如果该查询不可用，尝试将继续；登录永远不会因此失败。travel 的位置仅在登录成功完成后更新。

暴力破解与锁定

brute 模式决定 5 次失败之后会发生什么：

封禁：用户必须先重置密码，才能再次登录。
验证：账户锁定 15 分钟，下一次尝试需要额外验证。
已关闭 或记录：不锁定。

暴力破解封禁后，密码重置仍然可用，且重置会清除锁定。您的团队也可以在控制台中解锁账户。如果您从未保存过防护设置，则适用更简单的规则：5 次密码错误会将账户锁定 15 分钟。

机器人分数与设备信号

在运行时调用中通过以下请求头发送设备信号。托管页面会自动为您发送。

请求头	内容
`X-Didit-PID`	持久设备 ID，长度为 8 至 128 个字符，可使用 `A-Z a-z 0-9 . _ : -` 中的字符。
`X-Didit-FP-Hash`	设备指纹。
`X-Didit-FP-Bot-Score`	0 到 1 之间的机器人分数。超出该范围的值将被忽略。

这些信号只是决策的上下文，不是身份证明。它们还会随每个登录事件一起传递，规则可以读取 event.device.bot_score。

AUTOMATION_FRAMEWORK_DETECTED 是另一项检查。它是验证会话上的一项设备与 IP 分析警告，在验证 SDK 报告浏览器自动化框架时触发。它不会在登录时运行。登录时，自动化行为由上述 bots 策略拦截。

验证挑战

受挑战的尝试会返回以下内容，而不是登录验证码：

{
  "protection_required": true,
  "challenge": "...",
  "methods": ["passkey", "email_code"],
  "options": { "...": "WebAuthn options when a passkey is offered" },
  "expires_in": 300
}

使用 POST protection/complete/ 完成验证：

{"challenge", "method": "email_code", "code"}，并附带发送到用户邮箱的 6 位验证码；或
{"challenge", "method": "passkey", "response"}，并附带 WebAuthn 响应。

5 分钟内最多允许 5 次尝试。如果用户没有可用的验证方式，接口将返回 403 {"error": "protection_factor_unavailable"}。

泄露密码

设置 breached_password_check: true 后，Didit 会将新密码和重置密码与已知的泄露密码进行比对。密码本身永远不会被发送到任何地方。泄露密码会被拒绝，并返回 password_breached。登录时，泄露密码计为一次 stuffing 匹配。如果检查不可用，则接受该密码。

攻击模式

在攻击进行期间开启攻击模式：

携带 {"duration_hours": 1}（或 6、24）调用 POST protection/attack-mode/，返回 201。
DELETE protection/attack-mode/ 可提前结束攻击模式。攻击模式也会在持续时间结束后自动结束。

攻击模式开启期间：

每次注册和登录都必须通过通行密钥验证。不接受邮箱验证码。新注册用户和没有通行密钥的用户，在攻击模式结束前无法完成操作。
来自 VPN、Tor 或数据中心网络的注册将被封禁。

速率限制

每个运行时路由都按应用、按 IP 进行限制：

路由	每分钟	每小时
发现接口与 JWKS	1,200	12,000
运行时 API 与托管页面	30	300
邮箱验证码、手机验证码与服务商回调	5	20

超出限制时，接口返回 429。如果返回了 Retry-After 请求头，请遵守其中的等待时间。登录尝试同样有每分钟限制：每个 IP 60 次、每个账户 15 次、每台设备 30 次、每个应用 3,000 次，以及每个手机号前缀每分钟 20 次短信或 WhatsApp 验证码请求。令牌刷新拥有独立的应用级配额，每分钟 6,000 次，因此刷新不会占用您的登录配额。

事件

每个决策都会记录为一条认证事件：risk_logged、attempt_challenged、attempt_blocked、challenge_passed、challenge_failed、attack_mode_started 和 attack_mode_ended。事件会显示匹配的策略。

测试

在沙盒应用中，测试您启用的每种模式：被封禁的尝试、通过和失败的验证、账户锁定及其重置，以及攻击模式的开启和关闭。请在界面中保留通用错误提示，避免泄露账户是否存在。

指南

身份认证

模型上下文协议（MCP）

Web SDK

原生 SDK

服务端 SDK

集成

撞库与暴力破解防护：登录机器人防护

配置防护

策略

暴力破解与锁定

机器人分数与设备信号

验证挑战

泄露密码

攻击模式

速率限制

事件

测试

​配置防护

​策略

​暴力破解与锁定

​机器人分数与设备信号

​验证挑战

​泄露密码

​攻击模式

​速率限制

​事件

​测试

配置防护

策略

暴力破解与锁定

机器人分数与设备信号

验证挑战

泄露密码

攻击模式

速率限制

事件

测试