JWT(JSON Web Token)

JWT 是鉴权中常用的一种令牌(token)格式标准,定义在 RFC 7519。一句话概括:把「你是谁、你有什么权限、什么时候过期」这些信息,由服务端签名后打包成一个字符串,交给客户端保存;之后每次请求带上它,服务端验签即可确认身份。

初学者容易误以为 JWT 是一种「鉴权框架」,其实它只是一套编码 + 签名的数据规范。真正的鉴权逻辑仍然由你的服务端代码决定。

一个 JWT 由三个 Base64URL 片段用 . 连接而成:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6IkFsaWNlIn0.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

三段分别是:

部分 内容 是否可读
Header 算法与类型,如 {“alg”:“HS256”,“typ”:“JWT”} 明文(仅 Base64 编码)
Payload 载荷 / 声明(claims),如 sub、exp、角色 明文
Signature 对前两段的签名 无法伪造,但可见

关键点:JWT 默认只是编码,不是加密。 任何拿到令牌的人都能解出 Payload 的内容。所以里面不能放密码、身份证号、内部密钥之类的敏感信息。

  • 用户用账号密码登录,服务端校验通过
  • 服务端签发一个 JWT(用密钥签名),返回给客户端
  • 客户端保存(localStorage / Cookie / 内存),之后请求时放到请求头
  • 服务端收到后只做验签 + 检查过期时间,从 Payload 直接读出身份,无需查询会话表
  • 验签通过即认为该请求可信

典型请求头:

Authorization: Bearer <token>
维度 Session JWT
状态存放 服务端保存会话状态 状态写在令牌里(无状态)
水平扩展 需要共享存储(Redis 等) 天然支持多实例
能否立即失效 能,删掉会话即可 较难,签发后在到期前一直有效
体积 只传 sessionId 每次都要携带完整载荷
适合场景 常规 Web 应用 多服务 / 微服务、跨域、移动端、SSO
  • API 鉴权:前后端分离项目中最主流的方案(Bearer Token)
  • 单点登录(SSO):一次登录,多系统互认
  • 一次性票据:邮箱验证、密码重置链接
  • 信息交换:在多方之间传递经过签名的可信声明
  • 必须显式校验签名算法,拒绝 alg 为 none 的令牌,防止「算法混淆攻击」
  • 设置合理的 exp 过期时间,并配合 refresh token 续期
  • Payload 不放敏感数据,它是可读的
  • 撤销困难:若要「立即踢下线」,需额外维护黑名单或令牌版本号
  • 存储位置:localStorage 易受 XSS 影响,HttpOnly Cookie 易受 CSRF 影响,按场景取舍
  • 密钥要够强并妥善保管,密钥泄露等于任何人都能签发身份

JWT 本身只是一串字符串,它安不安全,很大程度取决于客户端把它放在哪、浏览器怎么把它带到服务端。

存储位置 是否自动随请求带 能否被 XSS 读走 是否会被 CSRF 利用 说明
localStorage / sessionStorage 否,要前端手工加请求头 能,JS 直接读 不涉及 方便,但泄露面最大,令牌被偷后攻击者可在任意地点使用
内存变量 否 仅在页面执行期间可能被注入脚本取走 不涉及 刷新即丢,通常用来放 access token
Cookie 是,浏览器自动带 加了 HttpOnly 后读不到 会 服务端控制力最强,但最容易踩 CSRF

HttpOnly 只是 Set-Cookie 上的一个属性标记(RFC 6265)。带上它以后:

  • 该 Cookie 依然会随 HTTP 请求自动发送给同域接口
  • 但通过 document.cookie、fetch、XMLHttpRequest 等 JS 途径一律读不到
// 服务端下发
Set-Cookie: access_token=eyJ...; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=900

// 前端尝试读取 —— 拿不到
document.cookie;   // => "" 或只剩非 HttpOnly 的其它 cookie

所以要记住一句话:HttpOnly 防的是「偷读」,不是「盗用」。 攻击者没法用脚本把令牌抄走,但只要诱导用户浏览器发请求,浏览器照样会自动带上这个 Cookie —— 这就是 CSRF。

属性 作用
HttpOnly 禁止 JS 读取,堵死「XSS 直接偷令牌」这条路
Secure 只在 HTTPS 上发送,防明文链路嗅探
SameSite=Strict 完全禁止跨站请求携带,最安全,但会伤到「从外站点链接进来」的登录态
SameSite=Lax 跨站 GET 导航仍携带、POST 不携带,Web 应用的主流折中
SameSite=None 允许跨站携带,必须同时带 Secure,仅用于真跨站场景
Domain / Path 限定作用域,例如把 refresh cookie 锁在 /auth/refresh,业务接口根本看不到
Max-Age / Expires 持久化时长;不写就是会话 Cookie,关浏览器即失效
__Host- 前缀 强制 Secure + Path=/ + 不带 Domain,防止子域覆盖父域 Cookie

推荐写法(两个令牌分开、作用域不同):

Set-Cookie: access_token=eyJ...;  HttpOnly; Secure; SameSite=Lax;    Path=/;             Max-Age=900
Set-Cookie: refresh_token=eyJ...; HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh; Max-Age=1209600

SameSite=Lax 已经能挡掉大部分 CSRF,但别只依赖它:老浏览器可能忽略该属性,同站子域之间的请求也算 SameSite。生产环境应叠加 CSRF token 或校验 Origin。

方案 A:access 与 refresh 都放 HttpOnly Cookie(传统 Web / 同站前后端)

  • 登录成功后,服务端用 Set-Cookie 下发两个令牌
  • 浏览器自动携带,服务端中间件从 Cookie 取令牌、验签
  • 前端完全不用碰令牌,刷新页面也不掉登录态
  • 代价:天然存在 CSRF 面,必须配 SameSite + CSRF token + Origin 校验
  • 跨域前后端分离时更麻烦:需要 credentials: “include” 与严格的 CORS 白名单

方案 B:refresh 放 HttpOnly Cookie,access 放内存(SPA 主流做法)

  • 登录成功 → 服务端把 refresh token 放进 HttpOnly Cookie,把 access token 放在响应体 JSON 里返回
  • 前端把 access token 存进内存变量(不要进 localStorage),请求时放进请求头
  • 请求头:Authorization: Bearer <access_token>
  • access 过期(如 15 分钟)→ 前端捕获 401,静默调 /auth/refresh;浏览器自动带上 refresh Cookie,服务端验证后返回新 access,并同时轮换 refresh
  • 页面刷新后内存清空 → 应用启动时先试一次 /auth/refresh 恢复登录态
  • 好处:业务请求走请求头、根本不带 Cookie,天然免疫 CSRF;refresh 长期有效但 JS 读不到,XSS 也抄不走
  • 代价:前端要处理刷新逻辑,以及「并发 401 只刷新一次」的队列问题
对比项 方案 A:全放 Cookie 方案 B:refresh Cookie + access 内存
前端复杂度 低,几乎零代码 中,需处理刷新与并发 401
CSRF 风险 有,必须额外防护 业务请求不带 Cookie,基本免疫
XSS 影响 令牌读不走,但脚本可代替用户发请求 access 在内存,脚本执行期间仍可能被取用
刷新 / 多标签 自然保持 需启动时刷新一次
适用场景 服务端渲染、同站应用 前后端分离 SPA、跨域前端

无论选哪种:refresh token 一律只放 HttpOnly Cookie,绝不放进 JS 能读的地方。

落地顺序建议:先定 Payload,再定令牌数量与寿命,然后密钥、撤销、校验、传输。

字段 说明
iss 签发者标识;多系统 / 多环境时必须校验
sub 主体,一般放用户 ID;别放手机号、邮箱等敏感或会变更的值
aud 受众,区分「给哪个 API 用」,防止 A 系统的令牌被拿到 B 系统复用
exp 过期时间(UTC 秒),必须有
iat / nbf 签发时间 / 生效时间,便于审计与延迟生效
jti 令牌唯一 ID,用于黑名单与日志追踪
sid 会话 ID,用于「按设备踢下线」
role / scope 授权信息,越少越好;权限变动频繁时改为运行时查库

原则:最小必要。Payload 是明文、且每次请求都要传输,塞得越多越慢、也越容易泄露。

  • access token:5~15 分钟,无状态,服务端只验签不查库
  • refresh token:7~30 天,必须有状态(Redis / 数据库),因为它要能被撤销
  • 刷新即轮换(rotation):每次用 refresh 换 access,同时下发新 refresh,旧的立即作废
  • 令牌族(token family):给同一登录会话下的 refresh 记录血缘;一旦出现「已经被用过」的 refresh,说明它泄露了 → 撤销整族并强制重新登录
  • refresh 只能用于 /auth/refresh,不能访问业务接口(用 Path 与 aud 双重限制)
  • 单服务、内部系统:HS256 + 至少 32 字节随机密钥;密钥放环境变量或密钥管理服务,不进代码库
  • 多服务、需第三方验签:RS256(或更短的 ES256)。私钥只留在签发服务,其它服务只拿公钥验签
  • 用 JWKS 端点(如 /.well-known/jwks.json)分发公钥,靠 header 里的 kid 选密钥,支持平滑轮换
  • 服务端固定算法白名单,绝不根据令牌里的 alg 决定用什么算法验签,并明确拒绝 none
  • 轮换节奏:先并行发布新 kid(新旧公钥都能验),等旧令牌自然过期再下线旧密钥
方案 做法 代价
短 access + 可撤销 refresh 撤销只作用于 refresh,access 等自然过期 有几到十几分钟的「踢不干净」窗口,最常用
黑名单(jti) Redis 存已撤销 jti,过期时间对齐 exp 重新引入状态与查询开销
令牌版本号 用户表存 tokenVersion,校验时比对 每次请求要读一次用户信息(可缓存)
会话表(sid) 以会话为单位撤销,支持「查看登录设备」「踢下线」 需维护会话存储,已接近 Session 方案

结论:别指望 JWT 天然「即时失效」。真需要立刻踢人,就必须接受一点点状态 —— 这也是「JWT 完全无状态」最常被误解的地方。

  • 取令牌:明确来源优先级(Cookie 或 Authorization: Bearer,不要两种混用)
  • 解析 header,检查 alg 是否在白名单内,用 kid 找对应密钥
  • 验签(用恒定时间比较)
  • 检查 exp / nbf,并留 30~60 秒时钟偏移容差(leeway)
  • 检查 iss / aud
  • 需要时检查撤销状态(黑名单 / 版本号)
  • 把解析出的身份注入请求上下文,后续业务代码只认这个身份
  • 全程 HTTPS;Cookie 一律带 Secure
  • 在网关 / 边缘统一验签,内部服务复用身份;不要让每个微服务各实现一遍
  • 跨域时前端要带凭据(credentials: “include”),后端 CORS 白名单精确到域名,Access-Control-Allow-Origin 不能用星号通配符
  • 令牌不要放 URL query:会进浏览器历史、Referer 和服务器日志
攻击 原理 对策
XSS 窃取令牌 注入脚本读取存储 HttpOnly(读不到)+ 不用 localStorage + CSP + 输出转义
CSRF 借浏览器自动携带 Cookie 发请求 SameSite + CSRF token + 校验 Origin / Referer + 自定义请求头
算法混淆 把 RS256 改成 HS256,拿公开的公钥当 HMAC 密钥 服务端固定算法白名单
kid 注入 kid 指向文件路径 / SQL / URL kid 只允许在服务端白名单键表里查
重放 抓到令牌重复使用 短 exp + HTTPS;敏感操作加 jti 一次性校验
令牌泄露到日志 请求 URL / 日志里带令牌 不放 query,日志脱敏

想快速定参数,可以先照这份抄:

项目 建议值
access token 有效期 15 分钟(安全要求高可缩到 5 分钟)
refresh token 有效期 14 天(7~30 天),每次使用即轮换
签名算法 单服务 HS256;多服务 / 第三方验签 RS256 或 ES256
密钥强度 HMAC 密钥 ≥ 32 字节随机;RSA ≥ 2048 位
access 存放 方案 A 放 HttpOnly Cookie;方案 B 放内存 + 请求头
refresh 存放 HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh
时钟偏移容差 30~60 秒
可接受的撤销延迟 等于 access 有效期
令牌来源 Cookie 或请求头二选一,别混用
JWT 不是鉴权的全部,而是「一张由服务端签名、客户端随身携带、服务端只看不记」的通行证。它把状态从服务端搬进了令牌,换来扩展性,代价是撤销与过期管理更麻烦。

一张图回顾全篇(可缩放、拖拽、点击折叠):

# JWT 鉴权
## 是什么
- RFC 7519 令牌格式标准
- 编码 + 签名,不是加密
- 鉴权逻辑仍由服务端决定
## 三段结构
- Header 算法与类型
- Payload 声明 claims(明文)
- Signature 签名(不可伪造)
## 鉴权流程
- 登录校验通过
- 服务端签发令牌
- 客户端保存并携带
- 服务端验签 + 查过期
## 对比 Session
- 无状态 vs 服务端存状态
- 易扩展 vs 易失效
- 载荷大 vs 只传 sessionId
## 典型用途
- API 鉴权 Bearer
- 单点登录 SSO
- 一次性票据
- 信息交换
## 令牌存哪
- localStorage:最方便、泄露面最大
- 内存变量:刷新即丢,适合 access
- Cookie:自动携带,服务端控制力最强
- HttpOnly 防偷读,不防盗用
## Cookie 属性
- HttpOnly + Secure
- SameSite Strict / Lax / None
- Domain / Path / Max-Age
- __Host- 前缀
## 两种搭配方案
- 方案 A:access 与 refresh 都放 Cookie,简单但须防 CSRF
- 方案 B:refresh 放 Cookie + access 放内存,业务请求免疫 CSRF
- refresh 一律只放 HttpOnly Cookie
## 设计清单
- claims:iss / sub / aud / exp / jti,最小必要
- access 5~15 分钟,refresh 7~30 天
- 刷新即轮换 + 令牌族
- 单服务 HS256,多服务 RS256 + JWKS
- 固定算法白名单,拒绝 none
- 撤销:黑名单 / 版本号 / 会话表
- 校验顺序:来源 → alg → 验签 → exp → iss/aud
- 网关统一验签,令牌不放 URL
## 常见攻击
- XSS 窃取 → HttpOnly + CSP + 输出转义
- CSRF → SameSite + CSRF token + Origin 校验
- 算法混淆 → 固定算法白名单
- kid 注入 → 服务端白名单键表
- 重放 / 日志泄露 → 短 exp + 脱敏
## 参数基线
- access 15 分钟,refresh 14 天
- HMAC ≥ 32 字节,RSA ≥ 2048 位
- 时钟容差 30~60 秒
- 令牌来源二选一,别混用

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • jwt.txt
  • 最后更改: 2026/10/12 17:17
  • 由 张叶安