零信任平台JWT协议对接指南

本文档提供应用系统集成零信任平台 JWT (JSON Web Token) 认证的改造开发指南。文档详述了总体架构、核心交互场景、角色定义、接口规范以及各语言的接入示例，并特别强调了生产环境中的 SSO 故障逃生机制。

一、协议概述

JWT (JSON Web Token) 是一种开放标准 (RFC 7519)，用于在各方之间以 JSON 对象安全地传输信息。由于该信息是经过数字签名的，因此可以被验证和信任。

在零信任平台中，JWT 协议认证是一种非常轻量级的单点登录 (SSO) 方案。
认证核心思路：应用系统在需要登录认证时，重定向到网关 SSO 获取 JWT Token；前端带着此 Token 发送回调请求，应用后端拦截此请求，通过本地验签（推荐）或调用远端接口的方式验证 Token 合法性，验证通过后解析出用户信息（如用户名、邮箱等），并根据这些信息完成系统本地的登录逻辑验证，建立本地会话。

适用场景：

内部办公应用、SaaS 应用快速接入 SSO。

后端系统希望减少与 SSO 服务的网络交互，倾向于无状态的本地认证。

适合对安全性要求较高、希望避免由于 session 等有状态方案带来的扩展性问题的分布式系统。

二、总体架构与交互场景

根据应用部署位置与网络可达性的不同，JWT 集成通常分为以下两种场景流向：

2.1 场景一：内部 WEB 应用（网关代理）

当应用部署在公司内网，并通过零信任网关对外发布时。网关不仅负责 SSO 鉴权流程，还会进行持续的动态访问控制。

2.2 场景二：SaaS 应用（直连集成）

SaaS 应用通常部署在公有云或其他外部网络，无法直接被零信任网关代理。网关仅负责 SSO 用户身份认证，应用需要自己进行后续的会话管理。

三、角色定义

在基于 JWT 的单点登录架构中，涉及以下三个核心角色：

资源所有者 (User / Web Browser): 尝试访问受保护资源的用户。

SSO 认证中心 (Zero Trust Gateway): 负责认证用户身份，向合法的内部或 SaaS 应用颁发包含了用户信息的 JWT Token。

应用系统 (Application): 接入零信任平台 SSO 认证的业务系统。应用需要负责重定向用户去 SSO 登录，并在用户携带 JWT Token 回调时对其进行验证和最终放行。

四、集成准备与配置

在编写代码之前，请先在零信任平台的管理后台完成应用的发布并获取凭证：

4.1 管理后台配置

登录零信任平台管理后台。

发布一个 WEB 应用（需域名解析至网关，网关持续访问控制）或 SaaS 应用（无需域名解析，网关仅做单次鉴权）。

在"SSO 配置"选项中，将协议类型选择为 JWT。

4.2 获取关键凭据与秘钥

配置完成后，请记录以下信息，它们将在应用后端代码配置中使用：

SSO 服务地址 (sso_url): 获取 JWT 的入口地址，通常为 http(s)://sso.example.com（视具体环境而定）。

应用回调地址 (redirect_uri / targetUrl): 用户的应用业务地址，登录成功后 JWT 将携带在此 URL 的参数上回调给应用。

JWT 签名秘钥 (jwt_secret / public_key): （关键）如果你选择本地验证方式，需要在应用列表中获取网关发布的这套签名公钥。强烈建议妥善保管，切勿硬编码在代码中泄露至前端！

五、核心交互流程与接口说明

JWT SSO 认证核心分为三个步骤：重定向获取、接收 Token、验证 Token。

5.1 流程时序图

以下是完整的系统级交互时序：

时序步骤详细说明：

访问受保护资源：用户通过浏览器或客户端尝试访问应用系统中的受保护页面（如 /index.html）。

拦截器触发：应用系统的后端或前端网关上的拦截器启动，检查用户当前是否已具有有效的本地登录态（如有效的 Session 或 Cookie）。

发起重定向：如果未登录或会话已失效，应用系统向浏览器发出 302 Found 响应，要求重定向到零信任 SSO 认证中心的 /jwt/sso 接口，并在 targetUrl 参数中附带业务回调地址。

获取 Token 请求：浏览器根据指引，发起向 SSO 认证中心的请求。

(可选) 统一登录：如果用户在此之前没有在 SSO 建立过全局会话，SSO 将其重定向至统一登录页面。

(可选) 提交凭据：用户完成账号密码、扫码等形式的身份验证。

(可选) 建立全局会话：SSO 认证中心验证通过后，与用户建立起全局统一登录会话。在此期间访问其它接入 SSO 的应用不再需要重新验证密码。

签发 JWT Token：SSO 认证中心根据对应应用的配置信息和当前用户的身份，生成并使用私钥签发带有效期的 JWT Token。

携带 Token 回调：SSO 认证中心响应 302 Found，指挥浏览器跳转回最初传递的 targetUrl，并在 URL Query 中附带刚刚签发的 token（例如 ?token=eyJhbGci...）。

10.

带着 Token 访问应用：浏览器带着 token 重新访问应用系统。

11.

验证 Token (分歧点)：

A. 本地验签（推荐）：应用系统利用预先拿到的公开验签秘钥，对 Token 进行解密并验证合法性与有效性。运算在应用本地完成，性能高。

B. 远端验证：应用系统向 SSO 服务器发起 /jwt/check 接口请求，交由 SSO 远端验证 Token 合法性。

12.

提取身份信息：验签无误后获取该用户的唯一身份标识（如 userId, userNo 或 email 等）。

13.

比对本地库：应用系统使用提取到的 SSO 身份标识，与系统本身内的账户数据库进行关联和比对。

14.

生成系统级凭证：确认该用户具备访问权限后，应用系统在本地服务端建立会话凭据（如创建 Session 或发放 Cookie Token）。

15.

放行并响应：彻底完成登录状态转换，最终为用户呈现实质的业务页面内容或响应数据。

5.2 接口详细说明

步骤 1：去网关获取 JWT 凭据 (GET /jwt/sso)

改造要点：在原始系统拦截器判断用户凭据的地方改造成：如果用户凭据无效，直接 302 重定向到网关 SSO。

HTTP 请求
GET /jwt/sso

请求参数 (Query)

Name	Type	Required	Description
targetUrl	string	是	应用回调目标URL，用于认证成功后携带 Token 重定向。例：`http://www.example.com/index.html`

返回示例 (302 Response)

步骤 2：应用接收网关回调

应用系统需开发一个接口（或拦截器捕获自定义目标地址），接收上一步回调拼接的 URL：
GET http://www.example.com/index.html?token={jwtToken}

提取 URL 中的 token 参数即可进行下一步验证。

步骤 3：验证 JWT 合法性

应用系统获取到 token 后，需选择以下其中一种方式验证：

方式 A：本地验证（推荐，性能高）

根据 jwtToken 中指定的算法，结合从管理后台配置中获取的秘钥，在应用代码中进行本地验签。如果合法，直接解密 JWT Payload，从中获取用户信息字典（通常包括 userid, userNo, email 等属性）。

[!TIP]
为什么要优先使用本地验证？
本地验证不需要额外发起外部 HTTP 请求，大幅降低了 SSO 节点的流量压力并缩短了用户认证响应时间。这也是 JWT 协议无状态特性的最大优势。

方式 B：远端验证接口 (GET /jwt/check)

如果系统环境无法做本地高安全强度的解密运算，或者由于某种原因需要实时校验此 Token 被吊销的信息，可调用 SSO 网关远端验证接口。

HTTP 请求
GET /jwt/check

请求参数

Name	In	Type	Required	Description
token	query	string	否	参数中的 token 值，来源于上一步回调
Authorization	header	string	是(二选一)	格式为 `Bearer {token}`。通常推荐使用 Header 传递 Token

SDK Header 请求参数示例

{
  "Authorization": "Bearer {token}"
}

返回示例 (200 Response)

{
  "code": 10000,
  "msg": "成功",
  "data": {
    "userid": "zhangsan",
    "userNo": "zhangsan",
    "email": "zhangsan@xxx.com"
  }
}

返回结构

code: (number) 状态码：10000 成功；其它视为失效。

msg: (string) 错误或成功描述。

data: (object) 从 JWT 中解析出的用户信息字典。

userid: 用户账号。

userNo: 用户编号。

email: 用户邮箱。

步骤 4：生成本地应用会话

无论通过本地还是远端验证成功拿到用户信息字典后，应用系统的后端应该：

校验这个 userid 是否在自身的数据库中。

如果存在，调用本身系统的登录建权代码，生成应用系统对应的本地用户凭据（例如把数据查出来放入 Session，或者利用自己内部的一套 Token 管理发放在 Cookie 中）。

最后返回相应的业务页面。如果不存在用户，则给出错误提示。

六、代码示例

在这里提供各个后端语言对应的**本地验签解析（方式 A）**的核心代码片段参考。为保证安全，一般使用 HS256 / RS256 算法，这里以通用的拦截器验证提取 Payload 数据为主干示例。

6.1 Java (jjwt)

Java (Spring Boot Filter/Interceptor)

6.2 Go (golang-jwt)

Go (Gin Middleware)

6.3 Python (PyJWT)

Python (Flask App)

七、SSO 故障逃生机制（关键）

[!CAUTION]
无论接入哪种协议架构，SSO 环境故障可能直接导致核心应用全线瘫痪。
虽然 JWT 本地验签在认证环节不依赖外部 SSO 服务，但首次颁发/续发获取 Token 强依赖 SSO 服务存活。因此在对接时，必须实现"降级逃生"机制。

7.1 前端健康检查降级

应用系统自身可以通过一个无鉴权的公共探针接口定时检测（或者在请求重定向发生异常前拉取前端探针）：

应用前端通过 /api/health/sso 检查是否可以连通 SSO。

若健康检查失败或超时（设定 3 秒），则放弃执行 302 /jwt/sso，改为弹出一个应用本地写死的表单登录界面。

提示"统一认证平台暂时不可用，请使用本地用户名/密码方式进行临时登录"。

7.2 提供特权/本地入口保障

永远保留超管自留门：设计类似 http://www.example.com/login?fallback=1 的隐藏链接，当平台发生瘫痪时允许输入管理员本地账密（此账密储存于应用本地 DB 乃至写死在配置文件中）。

切勿把所有的超级管理员权限锁死在仅 SSO 进入，一旦外部关联系统奔溃便形成死结。

八、集成检查清单

上线前，请对照完成以下审核：

8.1 配置项核对

管理后台 Web/SaaS 应用正确配置开启，并且协议明确为 JWT。

后台登记获取的 JWT 签发 Secret Key 或 Public Key，妥善加密写入应用的 Server 环境中，不能硬编码。

targetUrl 地址完全正确并与系统实际可解析跳转接收目标一致。

8.2 校验方式审查

(如果使用本地方式) 明确解析出的 payload 中所包含数据结构确实是 JSON Object。

Token 解析出用户信息后立刻与本地系统的 User 数据完成了一次绑定与映射；并在本地 Session/Cookie 持久化存证，而不是每次请求都需要解析验证甚至远端请求一遍。

Token 在使用建权完毕后，尽量洗清请求 URL 上的残留，避免安全隐患跨站。

8.3 逃生测试演习

尝试人为修改 hosts 或屏蔽 SSO 接口，访问您的系统。

验证系统是否能在极短延迟后降级跳出本地登录页面。

验证通过特殊保留入口能否依然全站接管业务。

九、常见问题 (FAQ)

Q1: JWT Token 是可以随意解析的，那么安全如何保障？

A: JWT 分为 Header, Payload, Signature 三部分。确实 Payload 仅是做了 Base64Url 编码，并没有做加密。因此不要在 Token 中暴露除了基础唯一标识 (userid/userNo) 以外的隐私敏感数据。
它的安全性通过第三部分 Signature 防篡改保证。只有拥有网关分发的 Secret Key，才能算对哈希验证从而合法通过逻辑，任何篡改内容将导致验签失败拒绝抛错。

Q2: 验证完毕后 Token 可以扔掉吗？过期怎么处理？

A: 是的，当你通过 JWT 验签成功并提取了用户信息后，你应当把它丢弃，并在自己的系统中基于这个用户创建一个你们自己维护超时的服务端 Session，或一个全新的本地 Token。
因为 JWT 内部包含有网关设置的过期时间戳 (exp)。由于你业务系统的操作，网关不知道（它是无状态的）。如果直接复用 JWT 去代表系统生命周期，会导致常常用到一半突然失效（过期不可改）。

Q3: 使用远端验证方案 `/jwt/check`，显示 Header 没有传入 Token?

A: 请确认 HTTP 请求构造。必须在发送时使用 Header 名称为 Authorization。其值格式必须为 Bearer （最后有个空格），再拼上你的 jwt 字符串。

Q4: 签名校验经常报 InvalidSignature？

A: 请排查环境、配置平台里拿到的密钥是否发生过更新替换，或者在 Java/Go 代码里的签发方法（Sign Method / Alg）是否没对齐。平台通用的 HMAC 即 HS256 / SHA256，非对称的是 RS256。请与后台人员确认。

文档版本: v1.0 | 最后更新: 2026-03-12

零信任平台JWT协议对接指南

一、协议概述#

二、总体架构与交互场景#

2.1 场景一：内部 WEB 应用（网关代理）#

2.2 场景二：SaaS 应用（直连集成）#

三、角色定义#

四、集成准备与配置#

4.1 管理后台配置#

4.2 获取关键凭据与秘钥#

五、核心交互流程与接口说明#

5.1 流程时序图#

5.2 接口详细说明#

步骤 1：去网关获取 JWT 凭据 (GET /jwt/sso)#

步骤 2：应用接收网关回调#

步骤 3：验证 JWT 合法性#

方式 A：本地验证（推荐，性能高）#

方式 B：远端验证接口 (GET /jwt/check)#

步骤 4：生成本地应用会话#

六、代码示例#

6.1 Java (jjwt)#

6.2 Go (golang-jwt)#

6.3 Python (PyJWT)#

七、SSO 故障逃生机制（关键）#

7.1 前端健康检查降级#

7.2 提供特权/本地入口保障#

八、集成检查清单#

8.1 配置项核对#

8.2 校验方式审查#

8.3 逃生测试演习#

九、常见问题 (FAQ)#

Q1: JWT Token 是可以随意解析的，那么安全如何保障？#

Q2: 验证完毕后 Token 可以扔掉吗？过期怎么处理？#

Q3: 使用远端验证方案 /jwt/check，显示 Header 没有传入 Token?#

Q4: 签名校验经常报 InvalidSignature？#