3.3 KiB
3.3 KiB
Google Authenticator 动态码登录
保留原密码登录和 Google OAuth 登录,新增独立的“账号 + 六位动态码 + 图形验证码”登录方式。动态码登录不是强制双因素验证,不改变其他登录方式的认证规则。
部署
- 在现有业务数据库执行增量脚本
sql/totp_auth.sql,不需要修改sys_user或 Google 绑定表。 - 使用密码学安全随机源生成 32 字节并转为 Base64,通过环境变量
TOTP_ENCRYPTION_KEY配置;不要提交到代码仓库。所有后端实例使用相同密钥,备份必须与数据库分开保管。留空时无法新增绑定。更换密钥前必须迁移已有密文。 - 可选设置
TOTP_ISSUER,默认USDT PAY。使用 HTTPS,服务器和手机开启自动时间同步。 - 编译部署前后端。Redis 用于短期绑定和限流,必须可用。数据库凭据表采用 InnoDB。
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 登录;需要重置绑定时由管理员核实身份后通过受控流程处理,系统不公开免验证重置接口。
API
| 方法 / 路径 | 认证 / 请求 |
|---|---|
POST /auth/totp/login |
匿名;username, totpCode, code, uuid,其中 code 是图形验证码;返回原有 token 字段 |
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 或应用中开启登录请求体和绑定响应体采集。