差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
| jwt [2026/10/09 20:28] – 添加 JWT 速览思维导图 张叶安 | jwt [2026/10/12 17:17] (当前版本) – 把未生效的 %%credentials%% 改为等宽标记(方案 A) 张叶安 | ||
|---|---|---|---|
| 行 60: | 行 60: | ||
| - **存储位置**:localStorage 易受 XSS 影响,HttpOnly Cookie 易受 CSRF 影响,按场景取舍 | - **存储位置**:localStorage 易受 XSS 影响,HttpOnly Cookie 易受 CSRF 影响,按场景取舍 | ||
| - **密钥要够强并妥善保管**,密钥泄露等于任何人都能签发身份 | - **密钥要够强并妥善保管**,密钥泄露等于任何人都能签发身份 | ||
| + | |||
| + | ===== HttpOnly Cookie 与 JWT 的搭配 ===== | ||
| + | |||
| + | ==== 为什么要谈「令牌存哪」 ==== | ||
| + | |||
| + | JWT 本身只是一串字符串,它安不安全,很大程度取决于**客户端把它放在哪、浏览器怎么把它带到服务端**。 | ||
| + | |||
| + | ^ 存储位置 ^ 是否自动随请求带 ^ 能否被 XSS 读走 ^ 是否会被 CSRF 利用 ^ 说明 ^ | ||
| + | | '' | ||
| + | | 内存变量 | 否 | 仅在页面执行期间可能被注入脚本取走 | 不涉及 | 刷新即丢,通常用来放 access token | | ||
| + | | Cookie | 是,浏览器自动带 | 加了 '' | ||
| + | |||
| + | ==== HttpOnly Cookie 是什么 ==== | ||
| + | |||
| + | '' | ||
| + | |||
| + | - 该 Cookie 依然会**随 HTTP 请求自动发送**给同域接口 | ||
| + | - 但通过 '' | ||
| + | |||
| + | < | ||
| + | // 服务端下发 | ||
| + | Set-Cookie: access_token=eyJ...; | ||
| + | |||
| + | // 前端尝试读取 —— 拿不到 | ||
| + | document.cookie; | ||
| + | </ | ||
| + | |||
| + | 所以要记住一句话:**HttpOnly 防的是「偷读」,不是「盗用」。** 攻击者没法用脚本把令牌抄走,但只要诱导用户浏览器发请求,浏览器照样会自动带上这个 Cookie —— 这就是 CSRF。 | ||
| + | |||
| + | ==== HttpOnly 之外还要配齐哪些属性 ==== | ||
| + | |||
| + | ^ 属性 ^ 作用 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | %%__Host-%% 前缀 | 强制 '' | ||
| + | |||
| + | 推荐写法(两个令牌分开、作用域不同): | ||
| + | |||
| + | < | ||
| + | Set-Cookie: access_token=eyJ...; | ||
| + | Set-Cookie: refresh_token=eyJ...; | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== JWT 与 HttpOnly Cookie 的两种搭配方式 ==== | ||
| + | |||
| + | **方案 A:access 与 refresh 都放 HttpOnly Cookie(传统 Web / 同站前后端)** | ||
| + | |||
| + | - 登录成功后,服务端用 '' | ||
| + | - 浏览器自动携带,服务端中间件从 Cookie 取令牌、验签 | ||
| + | - 前端**完全不用碰令牌**,刷新页面也不掉登录态 | ||
| + | - 代价:天然存在 CSRF 面,必须配 SameSite + CSRF token + Origin 校验 | ||
| + | - 跨域前后端分离时更麻烦:需要 '' | ||
| + | |||
| + | **方案 B:refresh 放 HttpOnly Cookie,access 放内存(SPA 主流做法)** | ||
| + | |||
| + | - 登录成功 → 服务端把 **refresh token** 放进 HttpOnly Cookie,把 **access token** 放在响应体 JSON 里返回 | ||
| + | - 前端把 access token 存进内存变量(**不要进 localStorage**),请求时放进请求头 | ||
| + | - 请求头:'' | ||
| + | - access 过期(如 15 分钟)→ 前端捕获 401,静默调 ''/ | ||
| + | - 页面刷新后内存清空 → 应用启动时先试一次 ''/ | ||
| + | - 好处:业务请求走请求头、**根本不带 Cookie,天然免疫 CSRF**;refresh 长期有效但 JS 读不到,XSS 也抄不走 | ||
| + | - 代价:前端要处理刷新逻辑,以及「并发 401 只刷新一次」的队列问题 | ||
| + | |||
| + | ^ 对比项 ^ 方案 A:全放 Cookie ^ 方案 B:refresh Cookie + access 内存 ^ | ||
| + | | 前端复杂度 | 低,几乎零代码 | 中,需处理刷新与并发 401 | | ||
| + | | CSRF 风险 | 有,必须额外防护 | 业务请求不带 Cookie,基本免疫 | | ||
| + | | XSS 影响 | 令牌读不走,但脚本可代替用户发请求 | access 在内存,脚本执行期间仍可能被取用 | | ||
| + | | 刷新 / 多标签 | 自然保持 | 需启动时刷新一次 | | ||
| + | | 适用场景 | 服务端渲染、同站应用 | 前后端分离 SPA、跨域前端 | | ||
| + | |||
| + | 无论选哪种:**refresh token 一律只放 HttpOnly Cookie,绝不放进 JS 能读的地方。** | ||
| + | |||
| + | ===== JWT 整体设计清单 ===== | ||
| + | |||
| + | 落地顺序建议:先定 Payload,再定令牌数量与寿命,然后密钥、撤销、校验、传输。 | ||
| + | |||
| + | ==== 一、声明(claims)怎么填 ==== | ||
| + | |||
| + | ^ 字段 ^ 说明 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | 原则:**最小必要**。Payload 是明文、且每次请求都要传输,塞得越多越慢、也越容易泄露。 | ||
| + | |||
| + | ==== 二、令牌数量与生命周期 ==== | ||
| + | |||
| + | - **access token**:5~15 分钟,无状态,服务端只验签不查库 | ||
| + | - **refresh token**:7~30 天,**必须有状态**(Redis / 数据库),因为它要能被撤销 | ||
| + | - **刷新即轮换(rotation)**:每次用 refresh 换 access,同时下发新 refresh,旧的立即作废 | ||
| + | - **令牌族(token family)**:给同一登录会话下的 refresh 记录血缘;一旦出现「已经被用过」的 refresh,说明它泄露了 → 撤销整族并强制重新登录 | ||
| + | - refresh 只能用于 ''/ | ||
| + | |||
| + | ==== 三、密钥与算法 ==== | ||
| + | |||
| + | - 单服务、内部系统:'' | ||
| + | - 多服务、需第三方验签:'' | ||
| + | - 用 JWKS 端点(如 ''/ | ||
| + | - 服务端**固定算法白名单**,绝不根据令牌里的 '' | ||
| + | - 轮换节奏:先并行发布新 '' | ||
| + | |||
| + | ==== 四、撤销:JWT 的固有短板 ==== | ||
| + | |||
| + | ^ 方案 ^ 做法 ^ 代价 ^ | ||
| + | | 短 access + 可撤销 refresh | 撤销只作用于 refresh,access 等自然过期 | 有几到十几分钟的「踢不干净」窗口,最常用 | | ||
| + | | 黑名单('' | ||
| + | | 令牌版本号 | 用户表存 '' | ||
| + | | 会话表('' | ||
| + | |||
| + | 结论:**别指望 JWT 天然「即时失效」**。真需要立刻踢人,就必须接受一点点状态 —— 这也是「JWT 完全无状态」最常被误解的地方。 | ||
| + | |||
| + | ==== 五、服务端校验顺序 ==== | ||
| + | |||
| + | - 取令牌:明确来源优先级(Cookie 或 '' | ||
| + | - 解析 header,检查 '' | ||
| + | - 验签(用恒定时间比较) | ||
| + | - 检查 '' | ||
| + | - 检查 '' | ||
| + | - 需要时检查撤销状态(黑名单 / 版本号) | ||
| + | - 把解析出的身份注入请求上下文,后续业务代码只认这个身份 | ||
| + | |||
| + | ==== 六、传输、跨域与网关 ==== | ||
| + | |||
| + | - 全程 HTTPS;Cookie 一律带 '' | ||
| + | - 在网关 / 边缘统一验签,内部服务复用身份;不要让每个微服务各实现一遍 | ||
| + | - 跨域时前端要带凭据('' | ||
| + | - 令牌**不要放 URL query**:会进浏览器历史、Referer 和服务器日志 | ||
| + | |||
| + | ==== 七、常见攻击与对策对照 ==== | ||
| + | |||
| + | ^ 攻击 ^ 原理 ^ 对策 ^ | ||
| + | | XSS 窃取令牌 | 注入脚本读取存储 | '' | ||
| + | | CSRF | 借浏览器自动携带 Cookie 发请求 | '' | ||
| + | | 算法混淆 | 把 '' | ||
| + | | '' | ||
| + | | 重放 | 抓到令牌重复使用 | 短 '' | ||
| + | | 令牌泄露到日志 | 请求 URL / 日志里带令牌 | 不放 query,日志脱敏 | | ||
| + | |||
| + | ==== 参数基线速查 ==== | ||
| + | |||
| + | 想快速定参数,可以先照这份抄: | ||
| + | |||
| + | ^ 项目 ^ 建议值 ^ | ||
| + | | access token 有效期 | 15 分钟(安全要求高可缩到 5 分钟) | | ||
| + | | refresh token 有效期 | 14 天(7~30 天),每次使用即轮换 | | ||
| + | | 签名算法 | 单服务 '' | ||
| + | | 密钥强度 | HMAC 密钥 ≥ 32 字节随机;RSA ≥ 2048 位 | | ||
| + | | access 存放 | 方案 A 放 '' | ||
| + | | refresh 存放 | '' | ||
| + | | 时钟偏移容差 | 30~60 秒 | | ||
| + | | 可接受的撤销延迟 | 等于 access 有效期 | | ||
| + | | 令牌来源 | Cookie 或请求头二选一,别混用 | | ||
| ===== 小结 ===== | ===== 小结 ===== | ||
| 行 65: | 行 229: | ||
| > JWT 不是鉴权的全部,而是「一张由服务端签名、客户端随身携带、服务端只看不记」的通行证。它把状态从服务端搬进了令牌,换来扩展性,代价是撤销与过期管理更麻烦。 | > JWT 不是鉴权的全部,而是「一张由服务端签名、客户端随身携带、服务端只看不记」的通行证。它把状态从服务端搬进了令牌,换来扩展性,代价是撤销与过期管理更麻烦。 | ||
| - | ```mdk height=460 color=# | + | ===== 思维导图速览 ===== |
| + | |||
| + | 一张图回顾全篇(可缩放、拖拽、点击折叠): | ||
| + | |||
| + | ```mdk height=560 color=# | ||
| # JWT 鉴权 | # JWT 鉴权 | ||
| ## 是什么 | ## 是什么 | ||
| 行 73: | 行 241: | ||
| ## 三段结构 | ## 三段结构 | ||
| - Header 算法与类型 | - Header 算法与类型 | ||
| - | - Payload 声明 claims | + | - Payload 声明 claims(明文) |
| - | - Signature 签名 | + | - Signature 签名(不可伪造) |
| ## 鉴权流程 | ## 鉴权流程 | ||
| - 登录校验通过 | - 登录校验通过 | ||
| 行 81: | 行 249: | ||
| - 服务端验签 + 查过期 | - 服务端验签 + 查过期 | ||
| ## 对比 Session | ## 对比 Session | ||
| - | - 无状态 vs 服务端存储 | + | - 无状态 vs 服务端存状态 |
| - 易扩展 vs 易失效 | - 易扩展 vs 易失效 | ||
| - | - 载荷大 vs 只传 | + | - 载荷大 vs 只传 |
| ## 典型用途 | ## 典型用途 | ||
| - API 鉴权 Bearer | - API 鉴权 Bearer | ||
| - 单点登录 SSO | - 单点登录 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 | ||
| + | - 网关统一验签,令牌不放 | ||
| + | ## 常见攻击 | ||
| + | - XSS 窃取 → HttpOnly + CSP + 输出转义 | ||
| + | - CSRF → SameSite + CSRF token + Origin 校验 | ||
| + | - 算法混淆 → 固定算法白名单 | ||
| + | - kid 注入 → 服务端白名单键表 | ||
| + | - 重放 / 日志泄露 → 短 exp + 脱敏 | ||
| + | ## 参数基线 | ||
| + | - access 15 分钟,refresh 14 天 | ||
| + | - HMAC ≥ 32 字节,RSA ≥ 2048 位 | ||
| + | - 时钟容差 30~60 秒 | ||
| + | - 令牌来源二选一,别混用 | ||
| ``` | ``` | ||