Skip to content

动态口令(OTP) ​

功能说明 ​

动态口令(One-Time Password,OTP)用于为账号密码登录增加第二重身份验证。织信采用基于时间的一次性密码(TOTP):用户在身份验证器中绑定账号后,登录时除账号密码外,还需要输入身份验证器生成的动态验证码。

可使用支持 TOTP 的身份验证器,例如 Google Authenticator、Microsoft Authenticator、1Password 等。为获得最佳兼容性,建议使用默认参数:SHA1 算法、6 位动态码和 30 秒有效周期。

适用范围

OTP 是系统级账号安全能力,不按团队单独配置。账号一旦启用 OTP,使用账号密码登录时必须完成 OTP 验证,切换团队不需要重新验证。

当前 OTP 仅接入账号密码登录,短信验证码、邮箱验证码、微信、Google 和 SSO 等登录方式保持原有流程。

启用前准备 ​

启用 OTP 前,请完成以下准备:

  1. 确认账号数据库已创建 OTP 数据表,并已初始化 system.otp.* 配置项。
  2. 确认 Redis 服务可用。登录 Challenge、失败次数和账号锁定状态存储在 Redis 中。
  3. 为所有服务器启用时间同步服务。服务器时间偏差过大会导致动态码验证失败。
  4. 生成并配置 OTP Secret 加密密钥。
  5. 先使用测试账号完成绑定、登录、重新绑定和解绑验证,再决定是否开启强制绑定。

妥善保管加密密钥

system.otp.encryptionKey 用于加密账号的 OTP Secret。请将密钥保存在受控的加密配置中,不要写入代码、日志或公开文档。

账号完成绑定后,不要直接替换加密密钥。确需轮换密钥时,应配合 system.otp.encryptionKeyVersion 和数据迁移方案进行,否则已有绑定可能无法解密。

系统配置 ​

管理员可在管理后台的参数设置中维护以下配置。

配置项默认值说明
system.otp.enablefalse是否启用 OTP 功能。关闭后登录跳过 OTP,但保留已有绑定数据
system.otp.forceEnablefalse是否要求未绑定账号在登录后完成 OTP 绑定
system.otp.issuerInformat身份验证器中显示的发行方名称
system.otp.algorithmSHA1TOTP 摘要算法,可配置 SHA1、SHA256 或 SHA512
system.otp.digits6动态验证码位数
system.otp.periodSeconds30动态验证码的时间周期,单位为秒
system.otp.offsetWindow1允许当前时间窗口前后偏移的窗口数量
system.otp.challengeExpireSeconds300密码登录通过后,OTP 登录 Challenge 的有效期,单位为秒
system.otp.challengeMaxAttempts5单个 Challenge 允许的最大验证失败次数
system.otp.accountFailWindowSeconds900账号和 IP 的 OTP 失败次数统计窗口,单位为秒
system.otp.accountMaxAttempts10账号在统计窗口内允许的最大失败次数;小于等于 0 时不锁定账号
system.otp.accountLockSeconds300账号达到失败阈值后的锁定时长,单位为秒
system.otp.ipMaxAttempts30IP 在统计窗口内允许的最大失败次数;小于等于 0 时关闭 IP 限制
system.otp.encryptionKey无32 字节 AES 密钥的 Base64 编码,用于加密 OTP Secret
system.otp.encryptionKeyVersion1OTP Secret 加密密钥版本

当 system.otp.periodSeconds 为 30、system.otp.offsetWindow 为 1 时,系统会校验上一个、当前和下一个 30 秒时间窗口,用于容忍服务器与用户设备之间的小幅时间偏差。

推荐启用顺序 ​

  1. 配置 system.otp.encryptionKey 和 system.otp.encryptionKeyVersion。
  2. 保持 SHA1、6 位动态码、30 秒周期和 1 个偏移窗口的默认配置。
  3. 配置 Challenge、账号和 IP 的失败限制。
  4. 将 system.otp.enable 设置为 true。
  5. 使用测试账号完成全流程验证。
  6. 如需所有账号绑定,再将 system.otp.forceEnable 设置为 true。

配置兼容性

部分身份验证器不支持 SHA256、SHA512、非 6 位验证码或非 30 秒周期。账号绑定后修改算法、位数或周期,可能导致已有绑定无法继续使用。

登录规则 ​

OTP 总开关强制绑定账号已绑定账号密码登录结果
关闭任意任意按原流程登录,不验证 OTP
开启否否按原流程登录
开启否是密码通过后必须验证 OTP
开启是否登录后要求账号完成 OTP 绑定
开启是是密码通过后必须验证 OTP

system.otp.forceEnable 只影响尚未绑定 OTP 的账号。账号已经启用 OTP 后,无论是否开启强制绑定,账号密码登录都必须输入动态验证码。

已绑定账号登录 ​

  1. 用户输入账号和密码。
  2. 密码验证成功后,系统返回 OTP 登录 Challenge,不签发正式登录 Token。
  3. 用户输入身份验证器当前显示的动态验证码。
  4. OTP 验证成功后,系统消费 Challenge 和动态码,并签发正式登录 Token。

Challenge 默认 5 分钟后过期,且只能成功使用一次。同一时间窗口内已经成功使用的动态码不能再次用于登录。

强制绑定 ​

开启强制绑定后,未绑定账号仍先完成账号密码登录。前端获取登录信息时,otpBindRequired 返回 true,应立即引导用户进入绑定流程。

前端接入要求

强制绑定提示来自登录后的 getLoginInfo。自定义登录页或客户端需要检查 otpBindRequired,并在该值为 true 时展示 OTP 绑定界面。

绑定 OTP ​

首次绑定 ​

  1. 用户发起 OTP 绑定。
  2. 系统返回发行方、账号名和 otpauth:// 配置 URI。
  3. 客户端将配置 URI 渲染为二维码。
  4. 用户使用身份验证器扫描二维码。
  5. 用户输入当前账号密码和身份验证器生成的动态验证码。
  6. 验证成功后,系统启用 OTP,并撤销该账号已有的登录 Token。
  7. 用户使用账号密码和动态验证码重新登录。

不要泄露绑定信息

配置 URI 包含 OTP Secret。不要将 URI、二维码、Secret、动态验证码或完整 Challenge 写入日志、浏览器持久化存储或分析系统。

重新绑定 ​

重新绑定适用于用户更换手机或身份验证器的场景:

  1. 用户发起重新绑定,系统生成一份待确认的新配置。
  2. 用户使用新身份验证器扫描二维码。
  3. 用户输入当前密码和新身份验证器生成的动态验证码。
  4. 验证成功后,新配置替换原配置,系统撤销该账号已有的登录 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 后,应清除本地登录状态并跳转到登录页。

常见问题 ​

动态验证码始终不正确 ​

请依次检查:

  1. 手机和服务器是否已自动同步时间。
  2. 身份验证器中的发行方和账号是否为本次绑定生成的配置。
  3. 算法、位数和周期是否在绑定后被修改。
  4. 用户是否正在输入旧设备或旧绑定生成的验证码。
  5. 当前动态码是否已经成功使用过。

Challenge 已失效 ​

Challenge 可能已经过期、达到最大失败次数或已被成功使用。请返回登录页,重新提交账号和密码以获取新的 Challenge。

账号被 OTP 锁定 ​

等待 system.otp.accountLockSeconds 配置的锁定时间结束,或由管理员核验身份后重置 OTP 锁定。不要通过重置绑定来代替普通的锁定解除。

关闭 OTP 后已有绑定会怎样 ​

将 system.otp.enable 设置为 false 后,账号密码登录会跳过 OTP,但系统不会删除已有绑定。再次开启 OTP 后,已绑定账号恢复 OTP 验证。