跳到主要内容

Token 认证

外部系统接入卷王时,可以先用 JWT 完成身份认证,再使用卷王返回的访问令牌调用管理接口。本文说明这一流程,以及页面免登录、接口调用和智能体接入分别应使用哪一种 Token。

选择认证方式​

接入目标使用的凭证获取与使用方式
从门户、OA 或业务系统免登录进入卷王JWT 登录 Token使用卷王配置的签名密钥签发,放在页面链接的 token 参数中,或提交给 Token 登录接口
调用需要登录的管理接口访问令牌 accessToken从登录接口取得,通过 Authorization: Bearer ACCESS_TOKEN 请求头传递
让 AI 助手通过 MCP 操作问卷、考试智能体专用 Token在 个人中心 → 智能体接入 创建,在助手连接配置中使用

JWT 登录 Token 用于换取登录会话,不能直接当作管理接口的 accessToken。MCP 也有独立的授权校验,普通登录令牌不能替代智能体专用 Token。

如果需要让第三方应用通过 OAuth2 授权流程取得令牌,请阅读 OAuth2 集成。

准备 JWT 登录​

  1. 在卷王中准备接入用户,并配置其角色、项目和数据权限。Token 登录不会自动创建用户,也不会额外授予项目权限。
  2. 进入 管理后台 → 基础设施 → 配置管理 → 认证配置 → JWT 令牌管理,开启 JWT 登录。
  3. 选择用户匹配方式:按用户 ID 校验时,uid 填卷王用户编号;按用户名校验时,uid 填卷王用户名。
  4. 保存后复制本次生成的签名密钥,交由外部系统的服务端保存。完整配置说明见 JWT 单点登录。
密钥只显示一次

开启状态下重新保存 JWT 配置会生成新密钥,旧密钥签发的 JWT 将无法继续用于登录。对接系统应同步更新密钥;不要为了查看密钥而反复保存配置。

在服务端生成 JWT​

JWT 中需要包含用户标识和过期时间:

字段说明
uid必填,与后台选择的用户 ID 或用户名匹配方式一致
exp建议使用的过期时间,按 JWT 标准填写秒级时间戳,例如签发时的当前时间加 300 秒
expire_time兼容历史接入的过期时间,使用毫秒级时间戳;新接入建议统一使用 exp
jti外部系统自行签发时通常省略。非空时会校验卷王令牌管理中的登记记录,随意生成的 UUID 无法通过

exp 与 expire_time 至少提供一个有效值;两者同时提供且 exp 可解析时,以 exp 为准。服务端时间应保持准确,避免刚签发的令牌被判定过期。

下面以已引入 Hutool JWT 模块的 Java 服务为例,生成有效期为 5 分钟的登录 Token。该示例要求后台选择 按用户名校验,并提前设置服务端环境变量 SURVEYKING_JWT_SECRET:

import cn.hutool.jwt.JWTUtil;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

public class TokenLoginExample {
public static String createToken(String username) {
String secret = System.getenv("SURVEYKING_JWT_SECRET");
if (secret == null || secret.trim().isEmpty()) {
throw new IllegalStateException("请配置卷王 JWT 签名密钥");
}

Map<String, Object> payload = new HashMap<>();
payload.put("uid", username);
payload.put("exp", Instant.now().getEpochSecond() + 300);
return JWTUtil.createToken(payload, secret.getBytes(StandardCharsets.UTF_8));
}
}

使用按用户 ID 校验时,将 uid 的值改为对应的卷王用户编号。密钥按原始字符串使用,不要自行做 Base64 解码。

外部系统必须先验证自己的登录用户,再为该用户生成 Token;不能允许浏览器任意指定 uid。签名密钥不要放在前端代码、问卷配置或公开仓库中。

方式一:通过链接免登录​

将 JWT 拼接到用户需要打开的卷王页面,例如问卷填写页:

https://survey.example.com/s/SURVEY_ID?token=JWT_TOKEN

将域名、SURVEY_ID 和 JWT_TOKEN 替换为实际值。如果原链接已有查询参数,使用 &token=JWT_TOKEN 追加;也支持参数名 Token。

页面会调用 Token 登录接口,取得并保存登录会话,再加载当前用户信息。无论认证成功或失败,都会从浏览器地址栏移除 token 和 Token 参数。登录后仍受问卷发布状态、填写限制及账号权限约束。

请使用 HTTPS,并避免在访问日志、截图或第三方跳转中泄露完整链接。移除地址栏参数不代表 JWT 已被消费;在有效期内,持有该 JWT 的人仍可能再次使用它登录。

方式二:换取访问令牌调用接口​

以下示例使用默认接口前缀 /admin-api。部署在子目录或使用网关改写路径时,以本站实际对外地址为准。

1. 提交 JWT​

curl --request POST 'https://survey.example.com/admin-api/system/auth/token-login' \
--header 'Content-Type: application/json' \
--data '{"token":"JWT_TOKEN"}'

请求体中的 token 填完整 JWT,不加 Bearer 前缀。成功响应的相关字段如下,凭证均为占位文字:

{
"code": 0,
"data": {
"userId": 1,
"accessToken": "ACCESS_TOKEN",
"refreshToken": "REFRESH_TOKEN"
},
"msg": ""
}

只有 code 为 0 且取得有效 data.accessToken 才算登录成功,不能只检查 HTTP 200。接口还会返回 expiresTime,用于判断访问令牌的过期时间;它与输入 JWT 的过期时间分别管理。

2. 使用访问令牌​

后续请求带上 Authorization 请求头。例如,读取当前用户的权限信息:

curl 'https://survey.example.com/admin-api/system/auth/get-permission-info' \
--header 'Authorization: Bearer ACCESS_TOKEN'

Bearer 后保留一个空格。这里填写上一步返回的 accessToken,不能填写 JWT、refreshToken 或智能体专用 Token。实际可操作的接口和数据仍由卷王中的账号权限决定。

3. 刷新与退出​

访问令牌过期后,可用登录时返回的 refreshToken 刷新:

curl --request POST 'https://survey.example.com/admin-api/system/auth/refresh-token' \
--data-urlencode 'refreshToken=REFRESH_TOKEN'

刷新成功后,保存本次返回的令牌和有效期,后续请求使用新 accessToken。刷新失败时应重新完成登录,不要无限重试原令牌。刷新接口接收请求参数,上例使用表单提交。

需要结束当前会话时,提交当前访问令牌:

curl --request POST 'https://survey.example.com/admin-api/system/auth/logout' \
--header 'Authorization: Bearer ACCESS_TOKEN'

退出会移除该访问令牌及对应刷新令牌。外部系统也应清理本地保存的凭证。

令牌管理与失效范围​

  • 后台颁发的 JWT:在 系统管理 → JWT 令牌管理 颁发并保存完整 Token,后续可以按登记记录冻结。列表中的 复制 jti 只复制令牌标识,不能代替完整 JWT 登录。
  • 外部自行签发、不带 jti 的 JWT:不在后台逐条登记,不能单独冻结;应设置较短有效期。更换签名密钥会影响所有使用旧密钥签发的 JWT。
  • 已经换取的登录会话:与 JWT 分别管理。JWT 到期、冻结或更换签名密钥,不会自动撤销已经签发的 accessToken。需要结束会话时,通过退出接口,或在 系统管理 → OAuth 2.0 → 令牌管理 对相应记录执行强退。
  • 智能体专用 Token:在 个人中心 → 智能体接入 独立创建和撤销,完整值仅创建时显示一次。具体步骤见 MCP 快速开始。

常见问题​

现象检查与处理
1002000009,Token 登录未开启检查 JWT 登录开关,保存配置后刷新卷王页面
1002000008,Token 验证失败检查签名密钥、uid 匹配方式、用户是否存在及过期字段是否有效;携带 jti 时还需检查登记记录、冻结状态和有效期
1002000006,Token 已经过期重新签发短期 JWT,确认 exp 使用秒级时间戳,并校准服务端时间
页面登录成功,接口仍提示未登录检查是否使用返回的 accessToken、请求头格式是否正确,以及代理是否保留 Authorization
已认证,但无权查看或修改项目检查账号角色、项目协作及数据权限;认证成功不会扩大原有权限
带 Token 的链接被清理后仍未登录参数清理也会在认证失败时发生,需查看页面提示或 Token 登录接口返回的 code、msg
普通登录正常,MCP 连接失败改用智能体专用 Token,检查接入开关、令牌有效期和所选授权,参见 MCP 常见问题

排查时保留接口路径、响应码、时间和必要上下文即可;不要在工单、聊天或日志中公开完整 JWT、访问令牌、刷新令牌或签名密钥。