Files
usdt/docs/totp-login.md
T
2026-11-16 07:14:39 -05:00

45 lines
3.7 KiB
Markdown

# Google Authenticator 登录二次验证
仅提供密码登录和 Google OAuth 登录,不提供独立动态码登录。已绑定 Google Authenticator 的账号,在密码登录(含 `/simple-login`)及 Google 登录交换票据时,必须提供有效且未使用的六位授权码 `totpCode`,否则不签发令牌。未绑定账号无需填写。
## 部署
1. 在现有业务数据库执行增量脚本 `sql/totp_auth.sql`,不需要修改 `sys_user` 或 Google 绑定表。
2. 使用密码学安全随机源生成 32 字节并转为 Base64,通过环境变量 `TOTP_ENCRYPTION_KEY` 配置;不要提交到代码仓库。所有后端实例使用相同密钥,备份必须与数据库分开保管。留空时无法新增绑定。更换密钥前必须迁移已有密文。
3. 可选设置 `TOTP_ISSUER`,默认 `USDT PAY`。使用 HTTPS,服务器和手机开启自动时间同步。
4. 编译部署前后端。Redis 用于短期绑定和限流,必须可用。数据库凭据表采用 InnoDB。
PowerShell 生成密钥(在部署服务器交互环境执行,输出仅写入受控配置):
```powershell
$totpKeyBytes = New-Object byte[] 32
$totpRng = [Security.Cryptography.RandomNumberGenerator]::Create()
$totpRng.GetBytes($totpKeyBytes)
$env:TOTP_ENCRYPTION_KEY = [Convert]::ToBase64String($totpKeyBytes)
$totpRng.Dispose()
```
## 使用
- 先用密码或已绑定 Google 账号登录,打开“个人中心 → 账号安全 → Google Authenticator 动态码”。
- 输入本地密码生成二维码;用 Google Authenticator 扫码,或手动输入页面展示的设置密钥,再输入手机六位动态码确认绑定。二维码在浏览器本地生成。
- 临时绑定十分钟过期,未经验证不会启用。确认绑定所用码已消费,等手机刷新下一组码后再用于登录。
- 密码登录需输入本地用户名、密码和图形验证码;已绑定账号同时填写六位授权码,前导零必须保留。授权码不能单独作为登录凭据。
- 密码登录时,已绑定用户必须填写授权码。Google 授权返回后填写授权码并继续;票据只有 60 秒有效且仅能交换一次,验证失败或过期需重新发起 Google 登录。
- 解绑需要本地密码及未使用过的动态码。遗失认证器时,密码或 Google 身份均不能绕过授权码;需要重置绑定时由管理员核实身份后通过受控流程处理,系统不公开免验证重置接口。
## API
| 方法 / 路径 | 认证 / 请求 |
| --- | --- |
| `POST /login`、`POST /simple-login` | 原登录参数增加 `totpCode`,已绑定用户必填 |
| `POST /auth/google/exchange` | `ticket, totpCode`,已绑定用户必填授权码;失败后票据不可复用 |
| `GET /auth/totp/binding` | 当前 JWT;返回 `data.enabled`、`data.bound`,不返回密钥 |
| `POST /auth/totp/setup` | 当前 JWT + `password`;返回 `data.secret`、`data.otpauthUrl`,禁止缓存或记录响应 |
| `POST /auth/totp/bind` | 当前 JWT + `password, totpCode` |
| `POST /auth/totp/unbind` | 当前 JWT + `password, totpCode` |
时间步为 30 秒,SHA-1,6 位,容忍前后各一个时间步。数据库 CAS 原子消费时间步,包含绑定确认在内的同一时间步不可重复成功,也不能倒退使用旧码。账号每五分钟最多十次登录授权码验证尝试,管理操作另计十次。可在反向代理层对真实来源增加限流,不信任任意客户端传入的转发头。
凭据使用 AES-256-GCM 加密,绑定用户 ID 为附加认证数据。密钥不加入用户实体、常规响应或 JWT。数据库、Redis 异常时拒绝认证。不要在网关、APM 或应用中开启登录请求体和绑定响应体采集。