JWT + Refresh Token 双 Token 方案
文章目录
- JWT + Refresh Token 双 Token 方案
- 1. 背景
- 2. 架构设计
- 2.1 总体流程
- 2.2 Token 类型对比
- 2.3 JWT Payload 结构
- 3. 核心实现
- 3.1 配置
- 3.2 Token 生成（JwtTokenProvider）
- 3.3 登录返回双 Token（AuthController）
- 3.4 Token 刷新接口
- 3.5 前端 401 自动刷新拦截器
- 4. 安全性分析
- 4.1 Access Token 泄露
- 4.2 Refresh Token 泄露
- 4.3 type claim 验证
- 5. 与单 Token 方案对比
- 6. 适用场景
- 7. 注意事项
1. 背景
传统的单 Token JWT 方案存在一个矛盾：
| 过期时间短 | 过期时间长 | |
|---|---|---|
| 安全性 | ✅ Token 泄露影响小 | ❌ Token 泄露影响大 |
| 用户体验 | ❌ 频繁重新登录 | ✅ 无需频繁登录 |
双 Token 方案通过引入Access Token和Refresh Token两个 Token，同时兼顾安全性和用户体验。
2. 架构设计
2.1 总体流程
┌─────────────────────────────────────────────────────────┐ │ 登录 │ │ 用户名密码 / 手机验证码 / OAuth2 │ └────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 签发双 Token │ │ ├─ Access Token (30分钟, 用于 API 鉴权) │ │ └─ Refresh Token (7~14天, 仅用于刷新) │ └────────────────────┬────────────────────────────────────┘ │ ┌───────────┴───────────┐ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ 正常请求 │ │ Access Token │ │ 携带 Access │ │ 过期(401) │ │ 正常响应 │ │ │ └─────────────────┘ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 自动用 Refresh │ │ Token 换新 │ │ │ ├── 成功 → 重试请求 └── 失败 → 跳转登录 └─────────────────┘2.2 Token 类型对比
| 属性 | Access Token | Refresh Token |
|---|---|---|
| 用途 | API 鉴权（Authorization 头） | 换取新的 Access Token |
| 有效期 | 30 分钟 | 7 天（默认）/ 14 天（记住我） |
| 携带用户信息 | ✅ 含 email、avatar 等 | ❌ 仅含用户名 |
| 存储位置 | 前端 localStorage | 前端 localStorage |
| 服务端状态 | ❌ 无状态 | ❌ 无状态（JWK 验证） |
| 传输频率 | 每次 API 请求 | 仅过期时 |
| 泄露影响 | 影响 30 分钟 | 较长，但仅能用于刷新 |
2.3 JWT Payload 结构
Access Token：
{"sub":"zhangsan","type":"access","email":"zhangsan@example.com","avatar":"https://...","iat":1719200000,"exp":1719201800}Refresh Token：
{"sub":"zhangsan","type":"refresh","email":"","avatar":"","iat":1719200000,"exp":1719804800}通过typeclaim 区分两种 Token，JwtAuthenticationFilter只认type=access的 Token。
3. 核心实现
3.1 配置
app:jwt:secret:YourSecretKeyForJWT...access-token-expiration-ms:1800000# 30 分钟refresh-token-expiration-ms:604800000# 7 天（默认）refresh-token-remember-me-expiration-ms:1209600000# 14 天（记住我）3.2 Token 生成（JwtTokenProvider）
// 生成 Access Token（含用户信息）publicStringgenerateAccessToken(Stringusername,Stringemail,Stringavatar){returnbuildToken(username,email,avatar,accessTokenExpirationMs,"access");}// 生成 Refresh Token（根据 rememberMe 决定有效期）publicStringgenerateRefreshToken(Stringusername,booleanrememberMe){longexpiry=rememberMe?refreshTokenRememberMeExpirationMs:refreshTokenExpirationMs;returnbuildToken(username,null,null,expiry,"refresh");}3.3 登录返回双 Token（AuthController）
@PostMapping("/login")publicResponseEntity<ApiResponse<LoginResponse>>login(@Valid@RequestBodyLoginRequestrequest){// ... 认证逻辑 ...StringaccessToken=jwtTokenProvider.generateAccessToken(username,email,avatar);StringrefreshToken=jwtTokenProvider.generateRefreshToken(username,request.isRememberMe());LoginResponseresponse=newLoginResponse(accessToken,refreshToken,username,avatar);returnResponseEntity.ok(ApiResponse.success("登录成功",response));}3.4 Token 刷新接口
@PostMapping("/refresh")publicResponseEntity<ApiResponse<LoginResponse>>refresh(@RequestBodyMap<String,String>request){StringrefreshTokenValue=request.get("refreshToken");// 验证 Refresh Tokenif(!jwtTokenProvider.validateRefreshToken(refreshTokenValue)){returnResponseEntity.status(401).body(ApiResponse.error("refreshToken 无效或已过期"));}// 提取用户信息Stringusername=jwtTokenProvider.getUsernameFromRefreshToken(refreshTokenValue);// 签发新的双 Token（Refresh Token 轮换）StringnewAccessToken=jwtTokenProvider.generateAccessToken(username,email,avatar);StringnewRefreshToken=jwtTokenProvider.generateRefreshToken(username,false);returnResponseEntity.ok(ApiResponse.success("Token 刷新成功",response));}3.5 前端 401 自动刷新拦截器
// Axios 响应拦截器http.interceptors.response.use((response)=>response,async(error)=>{if(error.response?.status!==401)returnPromise.reject(error)// 刷新接口本身 401 → 跳转登录if(originalRequest.url==='/api/auth/refresh'){clearAuth();window.location.href='/login'returnPromise.reject(error)}// 用 Refresh Token 换新constres=awaitaxios.post('/api/auth/refresh',{refreshToken:localStorage.getItem('refreshToken')})const{token,refreshToken}=res.data.data localStorage.setItem('token',token)localStorage.setItem('refreshToken',refreshToken)// 重试原始请求originalRequest.headers.Authorization=`Bearer${token}`returnhttp(originalRequest)})4. 安全性分析
4.1 Access Token 泄露
- 有效期仅 30 分钟
- 攻击者只能在这 30 分钟内使用
- 用户刷新 Token 后旧的 Access Token 自动失效（因为 Refresh Token 轮换，但 Access Token 本身是无状态的，需等自然过期）
4.2 Refresh Token 泄露
- 传输频率极低（仅在过期时通过
/api/auth/refresh传输一次） - Refresh Token 轮换：每次刷新签发新的 Refresh Token，旧的不再有效
- 后续可升级为 Redis 存储（服务端有状态），支持手动撤销
4.3 type claim 验证
privatebooleanvalidateToken(Stringtoken,StringexpectedType){Claimsclaims=parseClaims(token);returnexpectedType.equals(claims.get("type",String.class));}JwtAuthenticationFilter只验证type=access的 Token- Refresh Token 即使被传给 API 接口，也会因 type 不匹配而被拒绝
5. 与单 Token 方案对比
| 对比项 | 单 Token | 双 Token（本方案） |
|---|---|---|
| Token 数量 | 1 个 | 2 个 |
| 过期时间 | 7~14 天（统一） | Access 30min + Refresh 7~14d |
| 安全性 | 泄露影响大 | 泄露影响小（30 分钟窗口） |
| 用户体验 | 无需用户额外操作 | 无感刷新 |
| 实现复杂度 | 简单 | 中等 |
| 服务端存储 | 无 | 无（完全无状态） |
| Token 撤销 | 只能等过期 | 可通过 Refresh Token 轮换实现软撤销 |
6. 适用场景
- Web 应用：Token 存储在 localStorage，Access Token 短过期 + Refresh Token 自动续期
- 移动端：Token 存储在安全存储区，减少重新登录频率
- 单点登录（SSO）：Refresh Token 作为长期凭证，Access Token 用于各子系统鉴权
7. 注意事项
- 前端必须处理并发刷新：多个请求同时 401 时，只发起一次刷新请求，其他请求排队等待（见
isRefreshing+pendingRequests实现） - Refresh Token 也要有合理有效期：7 天默认 + 14 天记住我，不宜过长
- HTTPS 传输：所有 Token 必须通过 HTTPS 传输，防止中间人窃取
- 后续可升级点：
- Refresh Token 存入 Redis → 支持手动撤销
- 登录设备管理 → 一个用户可撤销指定设备的 Refresh Token
- 指纹识别 → 绑定设备信息到 Refresh Token 中
