# 登录安全配置

> 登录、密码与会话的配置键、默认值和生效顺序，以及扩展注意事项、源码与测试入口。

Source: https://yile2020.github.io/fastapi-react-admin/reference/security-config/

操作步骤见[登录与安全](https://yile2020.github.io/fastapi-react-admin/features/login-security/)和[登录会话](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/)。本页供管理员查参数、开发者查实现与扩展入口。

## 配置按什么顺序生效？

每组还有一个总开关 `<分组>_CONFIG_STATUS`，设成 0 时整组不读数据库、回落到 `.env` 的值。反过来，**这些键在 `.env` 里写了也会被数据库里的值覆盖** —— 常见问题里[「`.env` 关了验证码，登录页还要输」](https://yile2020.github.io/fastapi-react-admin/reference/faq/#env-里设了-login_captcha_enabledfalse登录页还是要验证码)就是这个原因。

## 在参数配置中修改

入口是「系统管理 → 参数配置」，修改后不用重启。会话策略影响之后的登录；关闭验证码立即生效。

### 登录策略

<div className="doc-table-scroll" role="region" aria-label="安全配置表" tabIndex={0}>

| 键 | 默认值 | 说明 |
|---|---|---|
| `LOGIN_CAPTCHA_ENABLED` | `true` | 图形验证码；关掉立刻对所有人生效 |
| `LOGIN_MFA_ENFORCE` | `off` | `off` / `superuser` / `all`；没配 `MFA_SECRET_KEY` 时只能是 `off` |

</div>

### 口令与锁定

<div className="doc-table-scroll" role="region" aria-label="安全配置表" tabIndex={0}>

| 键 | 默认值 | 说明 |
|---|---|---|
| `USER_LOCK_THRESHOLD` · `USER_LOCK_SECONDS` | `5` · `300` | 账号连续失败几次、锁多少秒；阈值 0 = 不锁 |
| `USER_PASSWORD_MIN_LENGTH` · `USER_PASSWORD_MAX_LENGTH` | `6` · `32` | |
| `USER_PASSWORD_REQUIRE_SPECIAL_CHAR` | `false` | |
| `USER_PASSWORD_HISTORY_CHECK_COUNT` | `3` | 不能和最近几次相同 |
| `USER_PASSWORD_EXPIRY_DAYS` · `USER_PASSWORD_REMINDER_DAYS` | `365` · `7` | 0 = 永不过期 / 不提醒 |

</div>

### 会话策略

<div className="doc-table-scroll" role="region" aria-label="安全配置表" tabIndex={0}>

| 键 | 默认值 | 说明 |
|---|---|---|
| `SESSION_{WEB,DESKTOP,MOBILE}_IDLE_MINUTES` | `120` · `120` · `43200` | 5 分钟到 90 天 |
| `SESSION_{…}_ABSOLUTE_DAYS` | `7` · `7` · `90` | 1–365 |
| `SESSION_{…}_MAX` | `0` · `0` · `1` | 0 = 不限 |
| `SESSION_{…}_OVERFLOW` | `evict_idle` | 或 `deny` 拒绝新登录 |

</div>

## 在 .env 中修改

修改 `apps/api/backend/.env` 后需要重启后端。

<div className="doc-table-scroll" role="region" aria-label="安全配置表" tabIndex={0}>

| 键 | 默认值 | 说明 |
|---|---|---|
| `MFA_SECRET_KEY` | 空 | 加密 TOTP 密钥用；留空 = 不能开二次验证 |
| `LOGIN_IP_LOCK_THRESHOLD` · `LOGIN_IP_LOCK_SECONDS` | `30` · `900` | 单 IP 跨账号的失败锁定；阈值 0 = 关闭 |
| `TRUSTED_PROXIES` | `[]` | 反代的地址或网段。空 = 不采信任何转发头；部署在反代后面却不填，后端看到的 IP 全是反代的，IP 锁定、限流、登录日志里的 IP 都跟着错 |
| `TOKEN_EXPIRE_SECONDS` | `1800` | access token 有效期 |
| `SESSION_REFRESH_GRACE_SECONDS` | `30` | 上一枚 refresh token 的宽限期；生产环境不许低于 10 秒 |
| `LOGIN_CAPTCHA_EXPIRE_SECONDS` | `300` | 图形验证码有效期 |
| `MFA_CHALLENGE_SECONDS` · `MFA_CHALLENGE_ATTEMPTS` | `300` · `5` | 登录第二步的时限和次数 |
| `COOKIE_SECURE` | 跟着请求走 | HTTPS 生产站点显式设 `true`（生产模板已开启），refresh / OAuth2 state cookie 始终带 `Secure`；生产未设为 `true` 会告警。本地 HTTP 保持不配置，纯 HTTP 部署可设 `false` |
| `OAUTH2_GITHUB_*` · `OAUTH2_GOOGLE_*` | —— | 第三方登录的 Client ID / Secret |
| `OAUTH2_AUTO_REGISTER` · `OAUTH2_AUTO_REGISTER_ROLE` | `false` · —— | 陌生第三方账号是否自动建号、挂哪个角色（角色编码找不到就拒绝登录） |

</div>

TLS 在上游终结时，入口代理必须覆盖客户端传入的 `X-Forwarded-Proto`，web 容器会保留有效的 `http` / `https`，缺失或异常值回退到当前连接协议。web 明文端口仅对可信代理开放，并正确配置 Uvicorn 的 `--forwarded-allow-ips`。

完整的定义在 [`core/conf.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/core/conf.py) 的「用户安全」「登录」「登录会话」三段。

## 验证与限流规则

<details>
<summary>短信响应、失败计数与 MFA 校验细节</summary>

手机验证码这一路要先过图形验证码；同一个号 60 秒冷却、一天最多 10 条。**没注册、没验证过的号也返回「已发送」**，只是不真发：状态码、文案、冷却、耗时都和真发的一样，否则这个不用登录就能调的接口就成了一张号码核对表。短信厂商故障时也一样返回成功，失败记在短信发送日志里给管理员看。

错误提示**不区分**「用户不存在」「密码错」「账号已锁」，耗时也抹平了：bcrypt 校验一次约 190 ms，而查无此人只要约 5 ms，40 倍的差距不用任何统计手段就能看出来。所以用户不存在时也拿一个假哈希跑一遍等价的校验（[`auth_service.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/service/auth_service.py) 顶部的 `_DUMMY_PASSWORD_HASH`）。

登录接口本身还按「IP + 路径」限流：每分钟 5 次；取图形验证码的接口每 30 秒 5 次。

可改范围是**后端**卡的，不只是界面上的输入框（[`dynamic_config.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/utils/dynamic_config.py) 的 `DYNAMIC_INT_BOUNDS`）。曾经实测过：带管理员 token 直接调接口，最小长度能被写成 999，结果是所有人都改不了密码。

TOTP 使用 6 位数字、30 秒时间片、SHA-1，前后各容忍一个时间片的时钟误差，同一个码不能重复使用。恢复码格式为 `xxxx-xxxx`，不含容易混淆的 0 / O / 1 / I / L，数据库只存哈希。

登录第二步有 5 分钟、最多试 5 次。输错的动态码计入账号的失败次数；密码正确不会清零计数，必须通过第二步才会清零。

</details>

## 加一种登录方式或一个「踢人」入口要注意什么？

- **新的登录方式要过 `mfa_service.gate()`**：身份确认之后调它，决定是直接开会话还是进入第二步。手机验证码登录就是逐条照抄了密码登录的检查（IP 锁定、停用判定、密码过期、成败计数），验证码替代的只是「密码对不对」这一步 —— 只复用「开会话」那一段的话，这些检查全会漏掉。
- **不用登录就能调的新接口**，要加进 `TOKEN_REQUEST_PATH_EXCLUDE`，写完整路径、不要写成前缀。
- **新的「让某人下线」的入口**，只调 `session_store.revoke` / `revoke_user`，不要自己删 `fba:session*` 的 Redis key：这两个函数会顺带写原因、推实时消息、断开连接。会话改造之前，有 7 个文件各自删 token，其中一处只删了 access token —— 被踢的人刷新一下就回来了。

细节和踩过的坑在 [`common/security/AGENTS.md`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/common/security/AGENTS.md)「登录会话」一节。

## 代码在哪

- 登录流程：[`auth_service.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/service/auth_service.py) · 接口 [`api/v1/auth/auth.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/api/v1/auth/auth.py)
- 二次验证：[`mfa_service.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/service/mfa_service.py) · [`utils/totp.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/utils/totp.py)
- 会话：[`common/security/session.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/common/security/session.py) · 在线用户接口 [`monitor/online.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/api/v1/monitor/online.py)
- 密码策略：[`user_password_history_service.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/service/user_password_history_service.py) · 运行时配置 [`utils/dynamic_config.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/utils/dynamic_config.py)
- 第三方登录：[`plugin/oauth2/`](https://github.com/yile2020/fastapi-react-admin/tree/main/apps/api/backend/plugin/oauth2)
- 前端：登录页 [`sign-in.tsx`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/web/src/routes/_guest/sign-in.tsx) · 个人中心 [`pages/profile/`](https://github.com/yile2020/fastapi-react-admin/tree/main/packages/platform/src/pages/profile) · 在线用户 [`pages/log-online/`](https://github.com/yile2020/fastapi-react-admin/tree/main/packages/platform/src/pages/log-online) · 会话与刷新 [`auth/session.ts`](https://github.com/yile2020/fastapi-react-admin/blob/main/packages/platform/src/auth/session.ts)

## 怎么测的

下面列出已有测试文件和覆盖的行为，可沿链接查看具体断言。

<details>
<summary>查看已有后端与浏览器测试覆盖</summary>

后端连真实的数据库和 Redis：

- [`test_session.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/tests/api_v1/test_session.py)（29 条）：后台轮询不续命、离开超过空闲时长回来点一下也不复活、宽限期内回放同一组令牌、宽限期外作废整个会话、会话 ID 对得上但 secret 对不上**不**撤销（否则凭日志里看得到的会话 ID 就能把人踢下线）。其中几条做过变异检验：把对应的判断改掉，测试当场红。
- [`test_mfa.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/tests/api_v1/test_mfa.py)（16 条）：恢复码只能用一次、密码对了不清零失败计数、试满次数后令牌作废、被强制的人登录时绑定且不能自己关、没配密钥不能强制。
- [`test_auth.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/tests/api_v1/test_auth.py)：用户不存在和密码错的响应一样、**耗时**也一样、错密码不暴露账号已锁、强制下线连 refresh token 一起作废。
- [`test_phone_login.py`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/plugin/sms/tests/test_phone_login.py)：没注册 / 没验证的号看起来也「发了」、厂商故障和陌生号码不可区分、手机登录也要过二次验证。
- OAuth2 插件的 [`tests/`](https://github.com/yile2020/fastapi-react-admin/tree/main/apps/api/backend/plugin/oauth2/tests)：陌生账号默认不建号、state 绑定、只认已验证的邮箱。

浏览器端（Playwright）：[`mfa.spec.ts`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/web/e2e/tests/mfa.spec.ts)（个人中心开启 → 退出 → 再登录要动态码）、[`session.spec.ts`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/web/e2e/tests/session.spec.ts)（被强制下线时页面当场回到登录页并说明原因；一个标签页登出，其它标签页跟着回去；刷新时后端暂时连不上，停在「连不上服务器」而不是踢回登录页）、[`login-phone.spec.ts`](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/web/e2e/tests/login-phone.spec.ts)。

</details>
