230 lines
9.2 KiB
Markdown
230 lines
9.2 KiB
Markdown
# 鉴权说明
|
||
|
||
本文档说明当前已落地的鉴权基座（基础 session 鉴权 + M4 登录加固）。
|
||
|
||
## 当前 auth 模型
|
||
|
||
- 认证方式：`username/password`（可选启用 TOTP 二次验证）
|
||
- 会话方式：server-side session
|
||
- 客户端凭据：session cookie
|
||
|
||
## 持久化
|
||
|
||
所有 auth 相关数据存放在单一 App DB（`APP_DATABASE_URL`，默认 `sqlite:///./data/app.db`）中：
|
||
|
||
- `auth_users`：用户表（含 TOTP 字段 `totp_secret` / `totp_enabled`）
|
||
- `auth_sessions`：session token 哈希与过期时间
|
||
- `auth_login_throttle`：登录失败退避状态（按 IP / username 双键）
|
||
- `auth_recovery_code`：TOTP 恢复码哈希（一次性）
|
||
- `app_config`：runtime 配置持久化
|
||
|
||
## 首次启动与 bootstrap
|
||
|
||
如果 auth DB 中还没有任何用户，应用启动时会使用：
|
||
|
||
- `AUTH_BOOTSTRAP_USERNAME`
|
||
- `AUTH_BOOTSTRAP_PASSWORD`
|
||
|
||
创建首个 admin 用户。当前默认 bootstrap 值为：
|
||
|
||
- username: `admin`
|
||
- password: `admin`
|
||
|
||
首次登录后，系统会强制要求修改密码。
|
||
|
||
## 基础安全设计
|
||
|
||
当前这版已经落实的安全点：
|
||
|
||
- 密码不明文存储，使用 Argon2 哈希
|
||
- session cookie 为 `HttpOnly`
|
||
- cookie 使用 `SameSite=Lax`
|
||
- `Secure` cookie 在非 `development` 环境默认开启
|
||
- 写请求（POST/PUT/PATCH/DELETE）需携带 `X-CSRF-Token` header（SameSite=Lax + 自定义 header 纵深防御，无需 per-session token 值比对）
|
||
- session token 为随机生成，服务端只持久化 token hash
|
||
- session 有过期时间（默认 12 小时）与显式失效机制
|
||
|
||
---
|
||
|
||
## M4 登录加固
|
||
|
||
M4 在基础鉴权之上叠加了三层防御：防爆破/指数退避、CLI 逃生通道、可选 TOTP 二次验证。
|
||
|
||
### 1. 防爆破 / 指数退避
|
||
|
||
#### 机制
|
||
|
||
登录失败按指数增长延迟，目标是拖垮暴力枚举，同时不因此永久锁定账号。
|
||
|
||
**退避是延迟（429 + Retry-After），不是永久封号**——单 admin 场景下永久锁会被攻击者反向用来故意打锁，所以退避只增加等待时间，CLI 是最终逃生口。
|
||
|
||
#### 双键计算
|
||
|
||
每次登录请求同时按 **client IP** 和 **username** 各记一套失败计数，本次需等待时间 = 两者退避的**较大值**。
|
||
|
||
- 按 IP：堵单点暴力（攻击 IP 越敲越慢，合法用户换 IP 不受影响）
|
||
- 按 username：全局兜底（即便攻击者分布式换 IP 也有一层保护）
|
||
|
||
#### 指数公式
|
||
|
||
```
|
||
N_FREE = 3 — 前 3 次失败不延迟（免费次数）
|
||
BASE = 1 秒
|
||
CAP = 900 秒（15 分钟）
|
||
|
||
wait = min(CAP, BASE × 2^(failures - N_FREE)) （failures > N_FREE 时生效）
|
||
```
|
||
|
||
延迟示意：
|
||
|
||
| 累计失败次数 | 等待时间 |
|
||
| --- | --- |
|
||
| 1–3 | 0 秒（免费） |
|
||
| 4 | 2 秒 |
|
||
| 5 | 4 秒 |
|
||
| 6 | 8 秒 |
|
||
| 7 | 16 秒 |
|
||
| … | … |
|
||
| 13+ | 900 秒（封顶） |
|
||
|
||
成功登录后，该 IP 和 username 的退避状态**立即清零**。
|
||
|
||
#### 登录端点行为（`POST /api/auth/login`）
|
||
|
||
1. 先查退避（在窗口内直接 `429`，**不验密码**，节省 Argon2 计算并防止枚举）
|
||
2. 验密码失败 → 记一次失败（IP + username 各记），返回 `401`
|
||
3. 密码正确但 TOTP 启用且缺少 `totp_code` → 返回 `401 {totp_required: true}`，**不记失败**（这是正常两步流程的第一步，不是攻击信号）
|
||
4. 密码正确但 TOTP 验证失败 → 记一次失败，返回 `401`
|
||
5. 全部通过 → 清零退避状态，发 session cookie
|
||
|
||
#### 配置项
|
||
|
||
| 配置项 | 类型 | 默认 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `AUTH_LOGIN_THROTTLE_ENABLED` | bool（CONFIG_FIELDS） | `true` | 全局开关，关闭后整个退避机制 no-op |
|
||
| `AUTH_TRUST_FORWARDED_FOR` | bool（`.env` 部署级） | `false` | `true` 时取 `X-Forwarded-For` 最左作为 client IP；**反代后必须显式开启**，否则反代 IP 全视为同一 IP，按 IP 退避失效 |
|
||
|
||
> **反代部署注意**：`AUTH_TRUST_FORWARDED_FOR` 默认 `false`（直接用 socket IP）。部署在 nginx 等反代后面时，应设 `AUTH_TRUST_FORWARDED_FOR=true`，并确保反代正确设置 `X-Forwarded-For`。
|
||
|
||
---
|
||
|
||
### 2. CLI 逃生通道
|
||
|
||
#### 设计原则
|
||
|
||
CLI 通过 **直连本地 DB**（`get_session_local()`）工作，**无需 HTTP 服务器运行、无需任何已存凭据**（密码、恢复码均不需要）。拿到服务器 CLI 权限本身就意味着对系统有完全控制，因此这是可接受且必须存在的最终逃生口。
|
||
|
||
CLI 只动 auth 相关行（`auth_users` 的密码/TOTP 字段、`auth_login_throttle`、`auth_recovery_code`），**绝不**触碰用户数据表（`location`、`poo_records`、`public_ip_state` 等）。
|
||
|
||
入口：`python -m scripts.admin_cli <command>`
|
||
|
||
#### 子命令
|
||
|
||
| 命令 | 用途 | 逃生场景 |
|
||
| --- | --- | --- |
|
||
| `reset-password <username> [--password <pwd>]` | 重置密码（不带 `--password` 则交互式输入，不回显） | 忘记密码 |
|
||
| `unlock [--all \| --ip <ip> \| --username <u>]` | 清 `auth_login_throttle` 行 | 被退避锁住（429）时解锁 |
|
||
| `disable-totp <username>` | 关停 TOTP（清 secret + 删全部恢复码），**零凭据可执行** | 恢复码全丢也能进 |
|
||
| `reissue-totp <username>` | 生成新 TOTP secret 并打印 `otpauth://` URI | 设备丢失、需重新注册 Authenticator |
|
||
| `list-admin` | 列出所有用户与状态列 | 排障用 |
|
||
|
||
#### 使用示例
|
||
|
||
```bash
|
||
# 重置密码（不带 --password 时交互式 prompt，不回显）
|
||
python -m scripts.admin_cli reset-password admin
|
||
|
||
# 重置密码（非交互，脚本里用）
|
||
python -m scripts.admin_cli reset-password admin --password "newpassword"
|
||
|
||
# 解锁所有退避
|
||
python -m scripts.admin_cli unlock --all
|
||
|
||
# 解锁特定 IP
|
||
python -m scripts.admin_cli unlock --ip 1.2.3.4
|
||
|
||
# 解锁特定 username
|
||
python -m scripts.admin_cli unlock --username admin
|
||
|
||
# 关停 TOTP（零凭据，最终逃生口）
|
||
python -m scripts.admin_cli disable-totp admin
|
||
|
||
# 重新发放 TOTP secret（打印新 otpauth:// URI，扫码重新注册）
|
||
python -m scripts.admin_cli reissue-totp admin
|
||
|
||
# 查看用户列表
|
||
python -m scripts.admin_cli list-admin
|
||
```
|
||
|
||
在 Docker 容器内执行：
|
||
|
||
```bash
|
||
docker compose exec app python -m scripts.admin_cli <command>
|
||
```
|
||
|
||
#### `reissue-totp` 语义说明
|
||
|
||
- 对**已启用** TOTP 的用户：新 secret **立即在登录时生效**，旧 Authenticator 生成的码立即失效；**无需**再走 web `enable` 步骤。
|
||
- 现有恢复码**不被删除**——恢复码是独立的随机哈希值，与 TOTP secret 无密码学绑定，reissue 后恢复码依然有效（仍可用于登录）。
|
||
- 如果需要完整清理（secret + 所有恢复码），使用 `disable-totp`。
|
||
|
||
---
|
||
|
||
### 3. 可选 TOTP 二次验证
|
||
|
||
#### 设计
|
||
|
||
- TOTP 遵循 RFC 6238，使用 `pyotp` 库。
|
||
- 二维码在**前端**由 `qrcode.react` 渲染（后端只返回 `otpauth://` URI，不引图像依赖）。
|
||
- `totp_secret` 明文存库（与项目其他 secret 处理一致，靠数据库文件权限保护）。
|
||
- 恢复码以 Argon2 哈希存库，一次性（使用后标记 `used_at`）。
|
||
|
||
#### 启用流程
|
||
|
||
1. **setup**（`POST /api/auth/totp/setup`）：生成 pending secret，返回 secret、`otpauth://` URI、10 个明文恢复码（**仅此一次**）；此时 `totp_enabled` 仍为 `false`。
|
||
2. **扫码**：用 Authenticator App 扫前端渲染的二维码（或手动输入 secret）。
|
||
3. **enable**（`POST /api/auth/totp/enable`）：输入当前 6 位码确认 → `totp_enabled` 变为 `true`。
|
||
4. 妥善保存恢复码（不会再次展示）。
|
||
|
||
#### 停用流程
|
||
|
||
**web 停用**（`POST /api/auth/totp/disable`）：需提供当前密码或当前 6 位 TOTP 码。成功后清 secret、删全部恢复码，恢复纯密码登录。
|
||
|
||
**CLI 停用**（逃生口，恢复码全丢时）：`python -m scripts.admin_cli disable-totp admin`，零凭据，立即生效。
|
||
|
||
#### 登录二步流程
|
||
|
||
1. 提交 `POST /api/auth/login {username, password}` → 密码正确但 TOTP 已启用 → `401 {totp_required: true}`（不发 session）
|
||
2. 前端切到第二屏，提交 `POST /api/auth/login {username, password, totp_code}` → 通过 → 发 session cookie
|
||
|
||
`totp_code` 可以是 6 位 TOTP 动态码，也可以是 `xxxx-xxxx` 格式恢复码（命中即消费，不可复用）。
|
||
|
||
#### API 端点
|
||
|
||
| 端点 | 用途 |
|
||
| --- | --- |
|
||
| `POST /api/auth/totp/setup` | 生成 pending secret + URI + 恢复码（一次性明文返回） |
|
||
| `POST /api/auth/totp/enable` | 带当前 6 位码确认启用 |
|
||
| `POST /api/auth/totp/disable` | 带密码或当前码停用 |
|
||
| `GET /api/auth/totp` | 返回当前 TOTP 状态（`{enabled: bool}`），不返回 secret/恢复码 |
|
||
|
||
全部端点需要 session cookie（`GET /api/auth/totp` 不需 CSRF；其余写端点需 `X-CSRF-Token`）。
|
||
|
||
#### 配置项
|
||
|
||
| 配置项 | 类型 | 默认 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `AUTH_TOTP_ISSUER` | str（`.env` 部署级） | 空（回退 `app_name`） | 显示在 Authenticator App 里的 issuer 标签 |
|
||
|
||
---
|
||
|
||
## 受保护范围
|
||
|
||
当前 JSON API 端点（`/api/*`）需要 session cookie；写端点需额外携带 `X-CSRF-Token` header。
|
||
|
||
裸 ingestion 端点（`/location/record`、`/poo/record` 等设备调用端点）暂未收口到 session 保护（M3 计划引入 token 鉴权）。
|
||
|
||
## 下一步（不在当前范围）
|
||
|
||
- M3：token 鉴权（供脚本 / 设备 / 移动端调用 API），ingestion 端点收口。
|