# Google Authenticator 登录二次验证 仅提供密码登录和 Google OAuth 登录,不提供独立动态码登录。已绑定 Google 账号或 Google Authenticator 的账号,在密码登录(含 `/simple-login`)及 Google 登录交换票据时,必须提供有效且未使用的六位授权码 `totpCode`,否则不签发令牌。两者均未绑定的账号无需填写。 Google 身份绑定与 Authenticator 绑定分别记录在 `sys_user_google_oauth` 和 `sys_user_totp`。仅有 Google 身份绑定、缺少 Authenticator 凭据的旧账号会拒绝登录,需通过已有会话完成认证器绑定或联系管理员核实处理;不会自动生成密钥或仅检查输入非空后放行。 ## 部署 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 和 Authenticator 均未绑定的账号可直接使用密码及图形验证码登录。登录成功后提示前往账号安全完成绑定;选择“稍后处理”或关闭提示可直接进入系统。建议先绑定 Authenticator,再绑定 Google,防止下次登录因缺少动态码凭据被拒绝。 - 先用密码或已绑定 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 或应用中开启登录请求体和绑定响应体采集。