> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit 为注册和登录提供机器人防护，可拦截机器人、撞库、暴力破解、一次性邮箱、高风险网络及异常异地登录，并支持攻击模式。

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

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

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

## 配置防护

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

```json theme={null}
{
  "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 之间的机器人分数。超出该范围的值将被忽略。 |

这些信号只是决策的上下文，不是身份证明。它们还会随每个[登录事件](https://docs.didit.me/zh/authentication/events-and-webhooks.md)一起传递，规则可以读取 `event.device.bot_score`。

> [!NOTE]
>
> `AUTOMATION_FRAMEWORK_DETECTED` 是另一项检查。它是**验证会话**上的一项 [设备与 IP 分析警告](https://docs.didit.me/zh/core-technology/ip-analysis/warnings-ip-analysis.md)，在验证 SDK 报告浏览器自动化框架时触发。它不会在登录时运行。登录时，自动化行为由上述 `bots` 策略拦截。

## 验证挑战

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

```json theme={null}
{
  "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 次，因此刷新不会占用您的登录配额。

## 事件

每个决策都会记录为一条[认证事件](https://docs.didit.me/zh/authentication/events-and-webhooks.md)：`risk_logged`、`attempt_challenged`、`attempt_blocked`、`challenge_passed`、`challenge_failed`、`attack_mode_started` 和 `attack_mode_ended`。事件会显示匹配的策略。

## 测试

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.