JWT 认证完整链路——从登录到退出的每一步都有一个真实项目在跑我做过一个政务系统的认证模块Java 从零实现了一套 JWT 认证——双 Token、黑名单、Cookie 和 Header 双通道提取、用户信息缓存、权限鉴权。这篇文章拆开这个模块的完整源码从 Token 结构到每条请求走过的每一步每一步都给出来源和原因。文章目录JWT 认证完整链路——从登录到退出的每一步都有一个真实项目在跑一、为什么不用 Session二、Token 结构——三段 Base64 拼起来的不只是一串字三、生成 Token——两个方法两种生命周期四、refreshToken 换发——Token 时效的权衡五、验证 Token——一行 parse 背后的三步六、完整请求链路——一条请求从进来到出去的 7 步七、黑名单——无状态的代价和补救八、Token 的两个通道——Header 和 Cookie 各自的用途九、认证和鉴权是两件事十、配置十一、结语一、为什么不用 SessionSession 是服务端状态。用户登录后服务端在内存或 Redis 里存一份session_id → 用户信息的映射浏览器通过 Cookie 回传 session_id。这个模型在单服务器时代够用。但政务系统有几个特点多节点部署——如果走 Session要么做 sticky session绑定到固定节点那台挂了全掉要么做 session 共享引入 Redis 集中存储单点故障风险Cookie 跨域限制——Cookie 的 domain 绑定了一个域名。如果系统有多个子域名app1.gov.cn、app2.gov.cn同域名下的 Cookie 不能跨子域共享——而 Session 依赖 Cookie前后端分离——前端可能是独立的 Vue/React 应用跟后端不同域。Session 的 Cookie 在同源策略下传不到后端JWT 解决了这三个问题Token 是自包含的——用户信息签名后放在 Token 里服务端不存状态。任何节点拿到 Token 用同一个密钥验签就能还原用户身份。Token 通过 Authorization Header 传不受 Cookie 同源策略限制。代价Token 一旦签发就无法主动失效不额外存储状态的话。这个代价引出了接下来的双 Token 黑名单设计。二、Token 结构——三段 Base64 拼起来的不只是一串字一个 JWT Token 长这样eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.HN_sWbXG-8_zpHjz5-TGKl06VfnKnCpN6A9TknR8VFs用句号拆开是三段Header → eyJhbGciOiJIUzI1NiJ9 Payload → eyJzdWIiOiJhZG1pbiJ9 Sig → HN_sWbXG-8_zpHjz5-TGKl06VfnKnCpN6A9TknR8VFsBase64 解码前两段Header{alg:HS256,typ:JWT}Payload{sub:admin,psnId:admin,psnName:管理员,unitId:U001,type:access,iss:browise,iat:1781683991,exp:1781691191}Signature 的计算方式HMAC-SHA256( Base64(Header) . Base64(Payload), secret )关键理解Payload 是明文 Base64任何人都能解出来看。Token 的安全性不靠加密——靠签名。没有 secret 的人可以读到 Payload 里的psnIdadmin——但他改不了。他如果把psnId改成superadmin然后重算 Base64——签名就对不上了——服务端一验就拒绝。所以 JWT 的设计哲学是Payload 可以公开看但不能改。三、生成 Token——两个方法两种生命周期登录成功后生成两个 Token。accessToken2 小时// 来源: JwtUtil.javapublicStringgenerateAccessToken(StringpsnId,StringpsnName,StringunitId){MapString,ObjectclaimsnewHashMap();claims.put(psnId,psnId);claims.put(psnName,psnName);claims.put(unitId,unitId);claims.put(type,access);// 标记类型returnJwts.builder().setClaims(claims).setSubject(psnId).setIssuer(browise).setIssuedAt(newDate()).setExpiration(newDate(System.currentTimeMillis()7200000))// 2小时.signWith(SignatureAlgorithm.HS256,secret).compact();}refreshToken7 天publicStringgenerateRefreshToken(StringpsnId){MapString,ObjectclaimsnewHashMap();claims.put(psnId,psnId);claims.put(type,refresh);// 标记类型——和 access 区分returnJwts.builder().setClaims(claims).setSubject(psnId).setIssuer(browise).setIssuedAt(newDate()).setExpiration(newDate(System.currentTimeMillis()604800000))// 7天.signWith(SignatureAlgorithm.HS256,secret).compact();}两个 Token 的区别不只是过期时间——type字段在验证时用来区分typerefresh的 Token 不能当 accessToken 用——它只能用来换新 Token。如果你把 refreshToken 放进 Authorization Header 调业务接口——Filter 层检查 type 不是 “access” 直接拒绝。四、refreshToken 换发——Token 时效的权衡为什么需要两个 TokenaccessToken 只有 2 小时因为它是高频传输的——每次请求都带着。如果 accessToken 有效期太长比如 7 天一旦泄露攻击者有 7 天时间可以任意调用接口——而 JWT 本身不存储状态你没法主动让它失效。但 2 小时太短——用户在一天之内可能被强制登出好几次体验极差。所以用一个 7 天的 refreshToken 来解决accessToken 过期后前端拿 refreshToken 去/auth/refresh换一个新的 accessToken——不用重新登录。accessToken 过期2小时 │ ├─ 前端请求 /api/xxx → 401 │ ├─ 前端拦截 401拿 refreshToken 调 /auth/refresh │ ├─ 验证 refreshToken 签名 有效期 │ ├─ 检查 refreshToken 是否在黑名单logout 时加入 │ ├─ 通过 → 生成新的 accessToken 返回 │ └─ 不通过 → 前端跳转登录页 │ └─ 前端拿到新 accessToken → 重试原请求refreshToken 是 httpOnly 的 Cookie——JS 不能读。这样即使前端被 XSS 攻击拿到了 accessToken攻击者也只能用 2 小时。要长期控制需要拿到刷新能力——但 refreshToken 在 httpOnly Cookie 里XSS 拿不到。五、验证 Token——一行 parse 背后的三步// 来源: JwtUtil.javapublicClaimsparseToken(Stringtoken){returnJwts.parser().setSigningKey(secret).parseClaimsJws(token).getBody();}parseClaimsJws背后做了三件事用 secret 重算签名——和 Token 里的 Signature 段比对。不匹配 → 抛出SignatureException——Token 被篡改过检查 exp——当前时间 exp → 抛出ExpiredJwtException——Token 已过期解析 Payload——验证通过后返回Claims对象——也就是 Payload 里的所有字段三步在一行代码里完成。如果任何一步失败——Filter 直接返回 401。六、完整请求链路——一条请求从进来到出去的 7 步JwtAuthFilter 拦截所有请求除了登录和公开接口。每条请求走 7 步HTTP 请求到达 │ ├─ ① 提取 Token │ ├─ Authorization: Bearer xxx → 截取 Bearer 之后的部分 │ └─ Cookie: BROWISE_ATxxx → 从 Cookie 取值备用通道 │ ├─ ② 验证 Token │ ├─ parseToken(token) → 签名校验 过期检查 │ └─ 解析 Claims → 拿到 psnId, type, iat │ ├─ ③ 黑名单检查jwtBlacklist │ ├─ isInvalid(psnId, iat) → 该用户此时刻之前的 Token 全失效 │ └─ isInvalidByToken(token) → 精确失效logout 单设备 │ ├─ ④ 加载用户信息userProfileCache │ ├─ 查 OP_PERSON → psnName, unitId, unitName │ ├─ 查 SYS_USER.STATUS → 账号是否启用 │ ├─ 查 SYS_USER_ROLE → 角色列表 │ └─ 缓存 1 小时TTL 内直接返回不查库 │ ├─ ⑤ 注入当前用户CurrentUser.set(profile) │ └─ ThreadLocal → 请求线程内全局可访问 │ ├─ ⑥ 账号状态检查 │ └─ !profile.isEnabled() → 403 账号已禁用 │ └─ ⑦ 权限检查menuAuthProvider.canAccess(path) ├─ 路径在 allowIdList 白名单 → 跳过鉴权 └─ 路径需匹配用户角色的菜单权限 → 不匹配返回 403第三步的黑名单是最容易被忽略的设计——它解决了Token 已经签发了但需要让它失效的问题。七、黑名单——无状态的代价和补救JWT 不存状态。但业务上需要主动失效——用户修改密码、管理员禁用账号、用户主动登出——这些场景要求已经签发的 Token 立刻不能用了。这个系统里黑名单分两层第一层用户级失效按签发时间当用户修改密码或管理员重置密码时——把这个用户的(psnId, 当前时间戳)写入黑名单。此后验证逻辑这样判断publicbooleanisInvalid(StringpsnId,longiat){LongcutoffTimeblacklist.get(psnId);// 从 Map 取该用户的最早失效时间if(cutoffTimenull)returnfalse;// 不在黑名单 → 正常returniatcutoffTime;// Token 签发时间 ≤ 失效时间 → 已失效}如果用户在 12:00 改了密码——写入blacklist[admin] 12:00。之后所有iat ≤ 12:00的 Token 全部作废——不管你是手机登录的还是浏览器登录的。因为改了密码意味着所有历史登录都不可信。第二层Token 级失效登出单设备用户点击退出登录——把当前这个 Token 写入精确黑名单publicbooleanisInvalidByToken(Stringtoken){returntokenBlacklist.contains(token);}logout 只失效当前设备——手机端的 Token 不受影响。黑名单的存储选择在演示环境里黑名单是内存 Map——服务重启后黑名单清空。生产环境换成 Redis——设置 key 的 TTL 等于 Token 的剩余有效时间——Token 过期后 key 自动删除不用手动清理。八、Token 的两个通道——Header 和 Cookie 各自的用途Token 的传输用了两个通道通道Token 类型场景为什么Authorization HeaderaccessTokenAJAX 请求不受 Cookie 同源限制跨域可用httpOnly CookieaccessToken页面跳转、form 提交浏览器自动携带不用前端手动加httpOnly CookierefreshToken刷新接口JS 不可读——XSS 攻击拿不到两个通道的原因是——header 方式需要前端在每个请求里手动加Authorization: Bearer xxx。但有些场景比如表单 POST 提交、a标签跳转前端控制不了 header。这时候 Cookie 作为备用通道——浏览器自动附在请求上——Filter 层两个地方都查有任意一个就继续验证。九、认证和鉴权是两件事很多刚接触权限系统的开发者把认证和鉴权混为一谈。这个模块里它们是两个独立的步骤认证Authentication 你是谁 → ①②③④⑤提取 Token → 验签 → 黑名单 → 加载用户 → 注入上下文 鉴权Authorization 你能做什么 → ⑦拿到用户角色和当前请求路径 → 匹配 → 放行或拒绝为什么分开因为有些接口不需要鉴权——只要你是登录用户就可以访问比如查看自己的个人信息。有些接口只需要认证不需要角色判断——比如全员可见的公告。十、配置browise:auth:enabled:truejwt:secret:browise-demo-local-dev-secret-key-must-be-32charsaccess-token-expire-ms:7200000# 2小时refresh-token-expire-ms:604800000# 7天issuer:browiseexclude-paths:-/auth/**-/captcha-/loginsecret在生产环境不应该写在配置文件里。放在环境变量或密钥管理服务中注入——${JWT_SECRET}。十一、结语JWT 认证不是一个引入一个库、写两行代码的事情。它的核心设计决策——双 Token、黑名单、双通道传输、认证鉴权分离——都是在回答同一个问题“不存状态的 Token 怎么安全地用”accessToken 短有效防止泄露窗口、refreshToken 长有效避免频繁登录、httpOnly Cookie 防 XSS、黑名单补上无状态的漏洞、用户缓存省掉每次查库——这五个设计合在一起才是一个生产可用的 JWT 认证模块。✅ 亮点从为什么不用 Session的自然动机出发按照请求链路逐层拆开 JWT 认证的完整实现——双 Token 生命周期、黑名单两级失效、Header/Cookie 双通道传输、认证鉴权分离——每层都给出了真实源码和为什么选这个设计的原因。适合正在实现或重构认证模块的开发者也适合面试中你们系统怎么做登录的的系统级回答。扩展方向OAuth2 授权码模式在政务系统中的应用、多系统单点登录SSO的 Token 共享方案、JWT Redis 组合实现有状态 Token 的折中方案。
JWT 认证完整链路——从登录到退出的每一步都有一个真实项目在跑我做过一个政务系统的认证模块Java 从零实现了一套 JWT 认证——双 Token、黑名单、Cookie 和 Header 双通道提取、用户信息缓存、权限鉴权。这篇文章拆开这个模块的完整源码从 Token 结构到每条请求走过的每一步每一步都给出来源和原因。文章目录JWT 认证完整链路——从登录到退出的每一步都有一个真实项目在跑一、为什么不用 Session二、Token 结构——三段 Base64 拼起来的不只是一串字三、生成 Token——两个方法两种生命周期四、refreshToken 换发——Token 时效的权衡五、验证 Token——一行 parse 背后的三步六、完整请求链路——一条请求从进来到出去的 7 步七、黑名单——无状态的代价和补救八、Token 的两个通道——Header 和 Cookie 各自的用途九、认证和鉴权是两件事十、配置十一、结语一、为什么不用 SessionSession 是服务端状态。用户登录后服务端在内存或 Redis 里存一份session_id → 用户信息的映射浏览器通过 Cookie 回传 session_id。这个模型在单服务器时代够用。但政务系统有几个特点多节点部署——如果走 Session要么做 sticky session绑定到固定节点那台挂了全掉要么做 session 共享引入 Redis 集中存储单点故障风险Cookie 跨域限制——Cookie 的 domain 绑定了一个域名。如果系统有多个子域名app1.gov.cn、app2.gov.cn同域名下的 Cookie 不能跨子域共享——而 Session 依赖 Cookie前后端分离——前端可能是独立的 Vue/React 应用跟后端不同域。Session 的 Cookie 在同源策略下传不到后端JWT 解决了这三个问题Token 是自包含的——用户信息签名后放在 Token 里服务端不存状态。任何节点拿到 Token 用同一个密钥验签就能还原用户身份。Token 通过 Authorization Header 传不受 Cookie 同源策略限制。代价Token 一旦签发就无法主动失效不额外存储状态的话。这个代价引出了接下来的双 Token 黑名单设计。二、Token 结构——三段 Base64 拼起来的不只是一串字一个 JWT Token 长这样eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiJ9.HN_sWbXG-8_zpHjz5-TGKl06VfnKnCpN6A9TknR8VFs用句号拆开是三段Header → eyJhbGciOiJIUzI1NiJ9 Payload → eyJzdWIiOiJhZG1pbiJ9 Sig → HN_sWbXG-8_zpHjz5-TGKl06VfnKnCpN6A9TknR8VFsBase64 解码前两段Header{alg:HS256,typ:JWT}Payload{sub:admin,psnId:admin,psnName:管理员,unitId:U001,type:access,iss:browise,iat:1781683991,exp:1781691191}Signature 的计算方式HMAC-SHA256( Base64(Header) . Base64(Payload), secret )关键理解Payload 是明文 Base64任何人都能解出来看。Token 的安全性不靠加密——靠签名。没有 secret 的人可以读到 Payload 里的psnIdadmin——但他改不了。他如果把psnId改成superadmin然后重算 Base64——签名就对不上了——服务端一验就拒绝。所以 JWT 的设计哲学是Payload 可以公开看但不能改。三、生成 Token——两个方法两种生命周期登录成功后生成两个 Token。accessToken2 小时// 来源: JwtUtil.javapublicStringgenerateAccessToken(StringpsnId,StringpsnName,StringunitId){MapString,ObjectclaimsnewHashMap();claims.put(psnId,psnId);claims.put(psnName,psnName);claims.put(unitId,unitId);claims.put(type,access);// 标记类型returnJwts.builder().setClaims(claims).setSubject(psnId).setIssuer(browise).setIssuedAt(newDate()).setExpiration(newDate(System.currentTimeMillis()7200000))// 2小时.signWith(SignatureAlgorithm.HS256,secret).compact();}refreshToken7 天publicStringgenerateRefreshToken(StringpsnId){MapString,ObjectclaimsnewHashMap();claims.put(psnId,psnId);claims.put(type,refresh);// 标记类型——和 access 区分returnJwts.builder().setClaims(claims).setSubject(psnId).setIssuer(browise).setIssuedAt(newDate()).setExpiration(newDate(System.currentTimeMillis()604800000))// 7天.signWith(SignatureAlgorithm.HS256,secret).compact();}两个 Token 的区别不只是过期时间——type字段在验证时用来区分typerefresh的 Token 不能当 accessToken 用——它只能用来换新 Token。如果你把 refreshToken 放进 Authorization Header 调业务接口——Filter 层检查 type 不是 “access” 直接拒绝。四、refreshToken 换发——Token 时效的权衡为什么需要两个 TokenaccessToken 只有 2 小时因为它是高频传输的——每次请求都带着。如果 accessToken 有效期太长比如 7 天一旦泄露攻击者有 7 天时间可以任意调用接口——而 JWT 本身不存储状态你没法主动让它失效。但 2 小时太短——用户在一天之内可能被强制登出好几次体验极差。所以用一个 7 天的 refreshToken 来解决accessToken 过期后前端拿 refreshToken 去/auth/refresh换一个新的 accessToken——不用重新登录。accessToken 过期2小时 │ ├─ 前端请求 /api/xxx → 401 │ ├─ 前端拦截 401拿 refreshToken 调 /auth/refresh │ ├─ 验证 refreshToken 签名 有效期 │ ├─ 检查 refreshToken 是否在黑名单logout 时加入 │ ├─ 通过 → 生成新的 accessToken 返回 │ └─ 不通过 → 前端跳转登录页 │ └─ 前端拿到新 accessToken → 重试原请求refreshToken 是 httpOnly 的 Cookie——JS 不能读。这样即使前端被 XSS 攻击拿到了 accessToken攻击者也只能用 2 小时。要长期控制需要拿到刷新能力——但 refreshToken 在 httpOnly Cookie 里XSS 拿不到。五、验证 Token——一行 parse 背后的三步// 来源: JwtUtil.javapublicClaimsparseToken(Stringtoken){returnJwts.parser().setSigningKey(secret).parseClaimsJws(token).getBody();}parseClaimsJws背后做了三件事用 secret 重算签名——和 Token 里的 Signature 段比对。不匹配 → 抛出SignatureException——Token 被篡改过检查 exp——当前时间 exp → 抛出ExpiredJwtException——Token 已过期解析 Payload——验证通过后返回Claims对象——也就是 Payload 里的所有字段三步在一行代码里完成。如果任何一步失败——Filter 直接返回 401。六、完整请求链路——一条请求从进来到出去的 7 步JwtAuthFilter 拦截所有请求除了登录和公开接口。每条请求走 7 步HTTP 请求到达 │ ├─ ① 提取 Token │ ├─ Authorization: Bearer xxx → 截取 Bearer 之后的部分 │ └─ Cookie: BROWISE_ATxxx → 从 Cookie 取值备用通道 │ ├─ ② 验证 Token │ ├─ parseToken(token) → 签名校验 过期检查 │ └─ 解析 Claims → 拿到 psnId, type, iat │ ├─ ③ 黑名单检查jwtBlacklist │ ├─ isInvalid(psnId, iat) → 该用户此时刻之前的 Token 全失效 │ └─ isInvalidByToken(token) → 精确失效logout 单设备 │ ├─ ④ 加载用户信息userProfileCache │ ├─ 查 OP_PERSON → psnName, unitId, unitName │ ├─ 查 SYS_USER.STATUS → 账号是否启用 │ ├─ 查 SYS_USER_ROLE → 角色列表 │ └─ 缓存 1 小时TTL 内直接返回不查库 │ ├─ ⑤ 注入当前用户CurrentUser.set(profile) │ └─ ThreadLocal → 请求线程内全局可访问 │ ├─ ⑥ 账号状态检查 │ └─ !profile.isEnabled() → 403 账号已禁用 │ └─ ⑦ 权限检查menuAuthProvider.canAccess(path) ├─ 路径在 allowIdList 白名单 → 跳过鉴权 └─ 路径需匹配用户角色的菜单权限 → 不匹配返回 403第三步的黑名单是最容易被忽略的设计——它解决了Token 已经签发了但需要让它失效的问题。七、黑名单——无状态的代价和补救JWT 不存状态。但业务上需要主动失效——用户修改密码、管理员禁用账号、用户主动登出——这些场景要求已经签发的 Token 立刻不能用了。这个系统里黑名单分两层第一层用户级失效按签发时间当用户修改密码或管理员重置密码时——把这个用户的(psnId, 当前时间戳)写入黑名单。此后验证逻辑这样判断publicbooleanisInvalid(StringpsnId,longiat){LongcutoffTimeblacklist.get(psnId);// 从 Map 取该用户的最早失效时间if(cutoffTimenull)returnfalse;// 不在黑名单 → 正常returniatcutoffTime;// Token 签发时间 ≤ 失效时间 → 已失效}如果用户在 12:00 改了密码——写入blacklist[admin] 12:00。之后所有iat ≤ 12:00的 Token 全部作废——不管你是手机登录的还是浏览器登录的。因为改了密码意味着所有历史登录都不可信。第二层Token 级失效登出单设备用户点击退出登录——把当前这个 Token 写入精确黑名单publicbooleanisInvalidByToken(Stringtoken){returntokenBlacklist.contains(token);}logout 只失效当前设备——手机端的 Token 不受影响。黑名单的存储选择在演示环境里黑名单是内存 Map——服务重启后黑名单清空。生产环境换成 Redis——设置 key 的 TTL 等于 Token 的剩余有效时间——Token 过期后 key 自动删除不用手动清理。八、Token 的两个通道——Header 和 Cookie 各自的用途Token 的传输用了两个通道通道Token 类型场景为什么Authorization HeaderaccessTokenAJAX 请求不受 Cookie 同源限制跨域可用httpOnly CookieaccessToken页面跳转、form 提交浏览器自动携带不用前端手动加httpOnly CookierefreshToken刷新接口JS 不可读——XSS 攻击拿不到两个通道的原因是——header 方式需要前端在每个请求里手动加Authorization: Bearer xxx。但有些场景比如表单 POST 提交、a标签跳转前端控制不了 header。这时候 Cookie 作为备用通道——浏览器自动附在请求上——Filter 层两个地方都查有任意一个就继续验证。九、认证和鉴权是两件事很多刚接触权限系统的开发者把认证和鉴权混为一谈。这个模块里它们是两个独立的步骤认证Authentication 你是谁 → ①②③④⑤提取 Token → 验签 → 黑名单 → 加载用户 → 注入上下文 鉴权Authorization 你能做什么 → ⑦拿到用户角色和当前请求路径 → 匹配 → 放行或拒绝为什么分开因为有些接口不需要鉴权——只要你是登录用户就可以访问比如查看自己的个人信息。有些接口只需要认证不需要角色判断——比如全员可见的公告。十、配置browise:auth:enabled:truejwt:secret:browise-demo-local-dev-secret-key-must-be-32charsaccess-token-expire-ms:7200000# 2小时refresh-token-expire-ms:604800000# 7天issuer:browiseexclude-paths:-/auth/**-/captcha-/loginsecret在生产环境不应该写在配置文件里。放在环境变量或密钥管理服务中注入——${JWT_SECRET}。十一、结语JWT 认证不是一个引入一个库、写两行代码的事情。它的核心设计决策——双 Token、黑名单、双通道传输、认证鉴权分离——都是在回答同一个问题“不存状态的 Token 怎么安全地用”accessToken 短有效防止泄露窗口、refreshToken 长有效避免频繁登录、httpOnly Cookie 防 XSS、黑名单补上无状态的漏洞、用户缓存省掉每次查库——这五个设计合在一起才是一个生产可用的 JWT 认证模块。✅ 亮点从为什么不用 Session的自然动机出发按照请求链路逐层拆开 JWT 认证的完整实现——双 Token 生命周期、黑名单两级失效、Header/Cookie 双通道传输、认证鉴权分离——每层都给出了真实源码和为什么选这个设计的原因。适合正在实现或重构认证模块的开发者也适合面试中你们系统怎么做登录的的系统级回答。扩展方向OAuth2 授权码模式在政务系统中的应用、多系统单点登录SSO的 Token 共享方案、JWT Redis 组合实现有状态 Token 的折中方案。
