JWT 单点登录

JWT 单点登录适合把卷王接入已有业务系统。外部系统使用卷王后台生成的签名密钥签发 JWT，再把 Token 拼到访问链接中，用户打开链接后即可自动登录卷王。

使用场景

• 外部门户、OA 或业务系统中已经完成用户登录，希望免密进入卷王
• 需要从其它系统跳转到指定问卷、考试或后台页面
• 希望通过统一身份系统控制用户入口，减少重复登录

配置步骤

1. 开启 JWT 登录

进入卷王后台的 基础设施 → 配置管理 → 认证配置，找到 JWT 令牌管理。

配置项说明：

• 开启状态：开启后，系统才会处理 URL 中的 Token 登录参数。
• 校验类型：决定 JWT 中 uid 字段按用户 ID 还是用户名解析。
• 签名密钥：保存配置时生成，只展示一次，需要复制给外部系统妥善保存。

warning

重新保存并生成密钥后，旧密钥签发的 JWT 将无法继续登录。正式环境更换密钥前，应先通知所有对接系统同步更新。

2. 选择用户匹配方式

JWT 登录通过 uid 字段定位卷王用户。

校验类型	uid 内容	适用场景
按用户 ID 校验	卷王用户 ID，例如 1	两个系统已经维护了卷王用户 ID 映射
按用户名校验	卷王用户名，例如 zhangsan	外部系统和卷王共用同一套用户名

外部系统签发 Token 前，需要确保对应用户已经在卷王中存在且状态正常。

3. 外部系统生成 JWT

外部系统使用 JWT 签名密钥 生成 Token。JWT 至少需要包含：

{
  "uid": 1,
  "exp": 1780000000
}

字段说明：

• uid：用户标识，根据后台配置填写用户 ID 或用户名。
• exp：标准 JWT 过期时间，使用秒级时间戳。

如果你使用卷王历史格式，也可以使用毫秒级 expire_time：

{
  "uid": "zhangsan",
  "expire_time": 1780000000000
}

tip

外部系统自行签发 JWT 时，不需要写入卷王的 JWT 令牌表，也不要求携带 jti。如果 Token 中携带 jti，卷王会按令牌管理表继续校验该 jti 是否有效、冻结或过期。

4. 拼接登录链接

把生成好的 JWT 拼到卷王访问地址上：

https://你的系统地址/目标路径?token=JWT字符串

也可以使用大写参数名：

https://你的系统地址/目标路径?Token=JWT字符串

用户打开链接后，前端会调用 Token 登录接口完成认证；成功或失败后，系统都会从浏览器地址栏移除 Token 参数，避免重复触发。

卷王后台颁发令牌

如果希望由卷王统一颁发可管理的 JWT，可以进入 系统管理 → JWT 令牌管理，点击 颁发令牌。

后台颁发的令牌会写入令牌管理表，支持：

• 查看令牌状态
• 复制 jti
• 冻结令牌
• 查看最近使用时间
• 过期后自动标记失效

这种方式适合需要审计、冻结和统一管理的集成场景。

安全建议

• 只在 HTTPS 链接中传递 Token，避免明文传输。
• Token 有效期尽量短，建议按分钟或小时设置，不要长期有效。
• 不要把 JWT 签名密钥写在前端代码、公开仓库或浏览器环境中。
• 外部系统生成 Token 前应确认用户身份已完成校验。
• 如果使用 URL 传递 Token，应避免在第三方页面、日志或 Referer 中泄露完整链接。

常见问题

打开带 Token 的链接后提示 Token 登录未开启怎么办？

进入 基础设施 → 配置管理 → 认证配置，确认 JWT 令牌管理 已开启，并且系统基础信息已经刷新。

外部系统签发的 Token 验证失败怎么办？

优先检查三项：签名密钥是否和卷王后台一致、uid 是否能匹配到卷王用户、exp 或 expire_time 是否已经过期。

外部系统自己签发的 Token 可以冻结吗？

不携带 jti 的外部 Token 是无状态校验，不能在卷王后台单独冻结。需要单独冻结时，可以改为由卷王后台颁发令牌，或让外部 Token 携带已登记的 jti。

修改 JWT 密钥后旧链接还能使用吗？

不能。旧链接中的 Token 是用旧密钥签发的，密钥变更后会验证失败，需要外部系统使用新密钥重新生成 Token。