Appearance
动态口令(OTP)
功能说明
动态口令(One-Time Password,OTP)用于为账号密码登录增加第二重身份验证。织信采用基于时间的一次性密码(TOTP):用户在身份验证器中绑定账号后,登录时除账号密码外,还需要输入身份验证器生成的动态验证码。
可使用支持 TOTP 的身份验证器,例如 Google Authenticator、Microsoft Authenticator、1Password 等。为获得最佳兼容性,建议使用默认参数:SHA1 算法、6 位动态码和 30 秒有效周期。
适用范围
OTP 是系统级账号安全能力,不按团队单独配置。账号一旦启用 OTP,使用账号密码登录时必须完成 OTP 验证,切换团队不需要重新验证。
当前 OTP 仅接入账号密码登录,短信验证码、邮箱验证码、微信、Google 和 SSO 等登录方式保持原有流程。
启用前准备
启用 OTP 前,请完成以下准备:
- 确认账号数据库已创建 OTP 数据表,并已初始化
system.otp.*配置项。 - 确认 Redis 服务可用。登录 Challenge、失败次数和账号锁定状态存储在 Redis 中。
- 为所有服务器启用时间同步服务。服务器时间偏差过大会导致动态码验证失败。
- 生成并配置 OTP Secret 加密密钥。
- 先使用测试账号完成绑定、登录、重新绑定和解绑验证,再决定是否开启强制绑定。
妥善保管加密密钥
system.otp.encryptionKey 用于加密账号的 OTP Secret。请将密钥保存在受控的加密配置中,不要写入代码、日志或公开文档。
账号完成绑定后,不要直接替换加密密钥。确需轮换密钥时,应配合 system.otp.encryptionKeyVersion 和数据迁移方案进行,否则已有绑定可能无法解密。
系统配置
管理员可在管理后台的参数设置中维护以下配置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
system.otp.enable | false | 是否启用 OTP 功能。关闭后登录跳过 OTP,但保留已有绑定数据 |
system.otp.forceEnable | false | 是否要求未绑定账号在登录后完成 OTP 绑定 |
system.otp.issuer | Informat | 身份验证器中显示的发行方名称 |
system.otp.algorithm | SHA1 | TOTP 摘要算法,可配置 SHA1、SHA256 或 SHA512 |
system.otp.digits | 6 | 动态验证码位数 |
system.otp.periodSeconds | 30 | 动态验证码的时间周期,单位为秒 |
system.otp.offsetWindow | 1 | 允许当前时间窗口前后偏移的窗口数量 |
system.otp.challengeExpireSeconds | 300 | 密码登录通过后,OTP 登录 Challenge 的有效期,单位为秒 |
system.otp.challengeMaxAttempts | 5 | 单个 Challenge 允许的最大验证失败次数 |
system.otp.accountFailWindowSeconds | 900 | 账号和 IP 的 OTP 失败次数统计窗口,单位为秒 |
system.otp.accountMaxAttempts | 10 | 账号在统计窗口内允许的最大失败次数;小于等于 0 时不锁定账号 |
system.otp.accountLockSeconds | 300 | 账号达到失败阈值后的锁定时长,单位为秒 |
system.otp.ipMaxAttempts | 30 | IP 在统计窗口内允许的最大失败次数;小于等于 0 时关闭 IP 限制 |
system.otp.encryptionKey | 无 | 32 字节 AES 密钥的 Base64 编码,用于加密 OTP Secret |
system.otp.encryptionKeyVersion | 1 | OTP Secret 加密密钥版本 |
当 system.otp.periodSeconds 为 30、system.otp.offsetWindow 为 1 时,系统会校验上一个、当前和下一个 30 秒时间窗口,用于容忍服务器与用户设备之间的小幅时间偏差。
推荐启用顺序
- 配置
system.otp.encryptionKey和system.otp.encryptionKeyVersion。 - 保持
SHA1、6 位动态码、30 秒周期和 1 个偏移窗口的默认配置。 - 配置 Challenge、账号和 IP 的失败限制。
- 将
system.otp.enable设置为true。 - 使用测试账号完成全流程验证。
- 如需所有账号绑定,再将
system.otp.forceEnable设置为true。
配置兼容性
部分身份验证器不支持 SHA256、SHA512、非 6 位验证码或非 30 秒周期。账号绑定后修改算法、位数或周期,可能导致已有绑定无法继续使用。
登录规则
| OTP 总开关 | 强制绑定 | 账号已绑定 | 账号密码登录结果 |
|---|---|---|---|
| 关闭 | 任意 | 任意 | 按原流程登录,不验证 OTP |
| 开启 | 否 | 否 | 按原流程登录 |
| 开启 | 否 | 是 | 密码通过后必须验证 OTP |
| 开启 | 是 | 否 | 登录后要求账号完成 OTP 绑定 |
| 开启 | 是 | 是 | 密码通过后必须验证 OTP |
system.otp.forceEnable 只影响尚未绑定 OTP 的账号。账号已经启用 OTP 后,无论是否开启强制绑定,账号密码登录都必须输入动态验证码。
已绑定账号登录
- 用户输入账号和密码。
- 密码验证成功后,系统返回 OTP 登录 Challenge,不签发正式登录 Token。
- 用户输入身份验证器当前显示的动态验证码。
- OTP 验证成功后,系统消费 Challenge 和动态码,并签发正式登录 Token。
Challenge 默认 5 分钟后过期,且只能成功使用一次。同一时间窗口内已经成功使用的动态码不能再次用于登录。
强制绑定
开启强制绑定后,未绑定账号仍先完成账号密码登录。前端获取登录信息时,otpBindRequired 返回 true,应立即引导用户进入绑定流程。
前端接入要求
强制绑定提示来自登录后的 getLoginInfo。自定义登录页或客户端需要检查 otpBindRequired,并在该值为 true 时展示 OTP 绑定界面。
绑定 OTP
首次绑定
- 用户发起 OTP 绑定。
- 系统返回发行方、账号名和
otpauth://配置 URI。 - 客户端将配置 URI 渲染为二维码。
- 用户使用身份验证器扫描二维码。
- 用户输入当前账号密码和身份验证器生成的动态验证码。
- 验证成功后,系统启用 OTP,并撤销该账号已有的登录 Token。
- 用户使用账号密码和动态验证码重新登录。
不要泄露绑定信息
配置 URI 包含 OTP Secret。不要将 URI、二维码、Secret、动态验证码或完整 Challenge 写入日志、浏览器持久化存储或分析系统。
重新绑定
重新绑定适用于用户更换手机或身份验证器的场景:
- 用户发起重新绑定,系统生成一份待确认的新配置。
- 用户使用新身份验证器扫描二维码。
- 用户输入当前密码和新身份验证器生成的动态验证码。
- 验证成功后,新配置替换原配置,系统撤销该账号已有的登录 Token。
新配置确认前,原 OTP 配置仍然有效。这样可以避免用户在扫码或验证中断后立即失去登录能力。
解绑
当 system.otp.forceEnable=false 时,用户可以输入当前密码和动态验证码解绑 OTP。解绑成功后,系统清除账号绑定并撤销已有登录 Token,用户需要重新登录。
当 system.otp.forceEnable=true 时,普通用户不能解绑 OTP。
状态与审计
OTP 状态接口返回以下信息,不会返回 Secret 或密文:
| 字段 | 说明 |
|---|---|
available | 系统是否已开启 OTP |
forceEnabled | 系统是否要求未绑定账号完成绑定 |
enabled | 当前账号是否已绑定并启用 OTP |
locked | 当前账号是否处于 OTP 锁定期 |
failedCount | 当前统计窗口内记录的失败次数 |
totalFailedCount | 历史累计失败次数 |
lastFailedTime | 最近一次 OTP 验证失败时间 |
lockedTime | 最近一次锁定的计划解锁时间 |
lastSuccessTime | 最近一次 OTP 验证成功时间 |
OTP 验证失败会同时记录账号和请求 IP 的失败次数。达到账号阈值后,账号会在配置的时间内被锁定;达到 IP 阈值后,该 IP 在当前统计窗口内不能继续提交 OTP 验证。
管理员处置
管理员可执行以下操作:
- 重置 OTP 锁定:清除账号当前的 OTP 失败计数和锁定状态,保留账号绑定及历史累计失败次数。
- 重置 OTP 绑定:删除账号的 OTP 配置并清除实时失败状态。用户需要重新绑定;如果系统已开启强制绑定,用户下次登录后会再次收到绑定提示。
重置绑定属于敏感操作。执行前应核验用户身份,并结合操作日志进行审计。
登录响应示例
已绑定账号的密码验证通过后,登录接口返回:
json
{
"errorCode": 0,
"needOtpVerify": true,
"challenge": "一次性登录Challenge",
"challengeExpiresIn": "2026-11-13T10:05:00.000+08:00",
"accountId": "账号ID",
"companyId": "团队ID",
"token": null
}客户端应提示用户输入动态验证码,并调用 verifyOtpLogin。只有该接口验证成功后,响应中才包含正式登录 Token。
绑定初始化响应示例
json
{
"issuer": "Informat",
"accountName": "user@example.com",
"uri": "otpauth://totp/Informat:user%40example.com?..."
}客户端应使用 uri 生成二维码,不应自行拼接 Secret 或修改算法参数。
绑定确认响应示例
json
{
"success": true,
"reloginRequired": true
}收到 reloginRequired=true 后,应清除本地登录状态并跳转到登录页。
常见问题
动态验证码始终不正确
请依次检查:
- 手机和服务器是否已自动同步时间。
- 身份验证器中的发行方和账号是否为本次绑定生成的配置。
- 算法、位数和周期是否在绑定后被修改。
- 用户是否正在输入旧设备或旧绑定生成的验证码。
- 当前动态码是否已经成功使用过。
Challenge 已失效
Challenge 可能已经过期、达到最大失败次数或已被成功使用。请返回登录页,重新提交账号和密码以获取新的 Challenge。
账号被 OTP 锁定
等待 system.otp.accountLockSeconds 配置的锁定时间结束,或由管理员核验身份后重置 OTP 锁定。不要通过重置绑定来代替普通的锁定解除。
关闭 OTP 后已有绑定会怎样
将 system.otp.enable 设置为 false 后,账号密码登录会跳过 OTP,但系统不会删除已有绑定。再次开启 OTP 后,已绑定账号恢复 OTP 验证。

