JWT双令牌认证：从原理到Spring Boot+Redis实战实现

在实际 Web 应用开发中单纯依赖一个长期有效的 JWT Token 进行身份认证会面临安全与体验的两难选择Token 有效期太短用户需要频繁重新登录有效期太长一旦 Token 泄露系统将长时间处于风险之中。为了解决这个问题大厂普遍采用“双令牌认证”方案使用短期的 access_token 负责接口访问长期的 refresh_token 负责无感刷新配合 Redis 黑名单实现 Token 的即时失效控制。本文将带你从零实现一套完整的 JWT 双令牌认证方案涵盖令牌生成、无感刷新、黑名单管理、安全防护等核心环节并提供生产环境下的配置建议和常见问题排查指南。1. 理解 JWT 双令牌认证的核心机制1.1 为什么需要双令牌设计传统的单 Token 方案存在明显缺陷。如果 Token 有效期设置为 2 小时用户每隔 2 小时就需要重新登录体验极差。如果设置为 30 天一旦 Token 被恶意获取攻击者可以在一个月内任意访问用户数据。双令牌方案通过职责分离解决这个问题access_token短期令牌负责业务接口访问认证有效期通常为 15-30 分钟refresh_token长期令牌仅用于获取新的 access_token有效期通常为 7-30 天当 access_token 过期时前端使用 refresh_token 请求刷新接口获取新的 access_token用户无需重新登录。即使 access_token 泄露由于其有效期很短风险窗口也很小。1.2 无感刷新的工作原理无感刷新的核心流程如下用户登录成功后服务端同时返回 access_token 和 refresh_token前端使用 access_token 访问需要认证的接口当 access_token 过期接口返回 401 状态码前端自动使用 refresh_token 调用刷新接口服务端验证 refresh_token 有效后签发新的 access_token前端使用新的 access_token 重试失败的请求用户无感知这个过程的关键在于前端需要拦截 401 响应并自动触发刷新流程。1.3 黑名单机制的必要性如果没有黑名单机制会出现严重的安全问题refresh_token 一旦签发在有效期内始终可用。如果用户主动退出登录或修改密码旧的 refresh_token 应该立即失效。Redis 黑名单方案通过存储已失效但未过期的 Token 来实现即时失效用户退出登录时将当前有效的 refresh_token 加入黑名单每次使用 refresh_token 时检查该 Token 是否在黑名单中黑名单中的 Token 有效期设置为与原 Token 剩余有效期一致自动过期清理2. 环境准备与项目结构设计2.1 技术栈选择Java 8基础开发语言Spring Boot 2.7Web 框架JJWTJWT 生成和解析库Redis黑名单存储Maven依赖管理2.2 Maven 依赖配置dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/scope scoperuntime/scope /dependency /dependencies2.3 项目目录结构src/main/java/com/example/jwtauth/ ├── config/ │ ├── RedisConfig.java │ └── SecurityConfig.java ├── controller/ │ ├── AuthController.java │ └── UserController.java ├── dto/ │ ├── LoginRequest.java │ ├── LoginResponse.java │ └── RefreshRequest.java ├── service/ │ ├── AuthService.java │ └── JwtService.java ├── filter/ │ └── JwtAuthenticationFilter.java └── entity/ └── User.java2.4 Redis 配置# application.yml spring: redis: host: localhost port: 6379 password: database: 0 timeout: 3000ms lettuce: pool: max-active: 8 max-wait: -1ms max-idle: 8 min-idle: 0// RedisConfig.java Configuration public class RedisConfig { Bean public RedisTemplateString, Object redisTemplate(RedisConnectionFactory factory) { RedisTemplateString, Object template new RedisTemplate(); template.setConnectionFactory(factory); template.setKeySerializer(new StringRedisSerializer()); template.setValueSerializer(new GenericJackson2JsonRedisSerializer()); return template; } }3. JWT 工具类设计与实现3.1 JWT 配置参数设计// JwtProperties.java Component ConfigurationProperties(prefix jwt) Data public class JwtProperties { private String secret your-secret-key-at-least-256-bits-long; private Long accessTokenExpire 30 * 60 * 1000L; // 30分钟 private Long refreshTokenExpire 7 * 24 * 60 * 60 * 1000L; // 7天 private String issuer your-app-name; }注意生产环境中的 secret 必须通过环境变量或配置中心管理不能硬编码在代码中。3.2 JWT 服务核心方法// JwtService.java Service Slf4j public class JwtService { Autowired private JwtProperties jwtProperties; Autowired private RedisTemplateString, Object redisTemplate; // 生成 access_token public String generateAccessToken(User user) { return Jwts.builder() .setSubject(user.getUsername()) .claim(userId, user.getId()) .claim(type, access) .setIssuer(jwtProperties.getIssuer()) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() jwtProperties.getAccessTokenExpire())) .signWith(SignatureAlgorithm.HS256, jwtProperties.getSecret()) .compact(); } // 生成 refresh_token public String generateRefreshToken(User user) { String refreshToken Jwts.builder() .setSubject(user.getUsername()) .claim(userId, user.getId()) .claim(type, refresh) .setIssuer(jwtProperties.getIssuer()) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() jwtProperties.getRefreshTokenExpire())) .signWith(SignatureAlgorithm.HS256, jwtProperties.getSecret()) .compact(); // 存储 refresh_token 与用户的映射关系用于单设备登录控制 String key refresh_token: user.getId(); redisTemplate.opsForValue().set(key, refreshToken, jwtProperties.getRefreshTokenExpire(), TimeUnit.MILLISECONDS); return refreshToken; } // 解析 JWT public Claims parseToken(String token) { try { return Jwts.parser() .setSigningKey(jwtProperties.getSecret()) .parseClaimsJws(token) .getBody(); } catch (ExpiredJwtException e) { log.warn(JWT token expired: {}, e.getMessage()); throw new RuntimeException(Token expired); } catch (Exception e) { log.error(JWT token parse error: {}, e.getMessage()); throw new RuntimeException(Invalid token); } } // 检查 token 是否在黑名单中 public boolean isTokenBlacklisted(String token) { String key blacklist: DigestUtils.md5DigestAsHex(token.getBytes()); return redisTemplate.hasKey(key); } // 将 token 加入黑名单 public void addToBlacklist(String token, long expireTime) { String key blacklist: DigestUtils.md5DigestAsHex(token.getBytes()); redisTemplate.opsForValue().set(key, 1, expireTime, TimeUnit.MILLISECONDS); } }3.3 Token 刷新逻辑实现// AuthService.java Service public class AuthService { Autowired private JwtService jwtService; Autowired private UserRepository userRepository; public LoginResponse refreshToken(String refreshToken) { // 验证 refresh_token 格式和签名 Claims claims jwtService.parseToken(refreshToken); // 检查 token 类型 if (!refresh.equals(claims.get(type))) { throw new RuntimeException(Invalid token type); } // 检查是否在黑名单中 if (jwtService.isTokenBlacklisted(refreshToken)) { throw new RuntimeException(Token has been revoked); } // 获取用户信息 Long userId claims.get(userId, Long.class); User user userRepository.findById(userId) .orElseThrow(() - new RuntimeException(User not found)); // 验证 refresh_token 是否与当前用户绑定的最新 token 一致 String storedToken (String) redisTemplate.opsForValue().get(refresh_token: userId); if (!refreshToken.equals(storedToken)) { // 不一致说明已在其他设备重新登录当前 token 失效 throw new RuntimeException(Token has been replaced); } // 生成新的 access_token String newAccessToken jwtService.generateAccessToken(user); // 将旧的 refresh_token 加入黑名单可选增强安全性 long expireTime claims.getExpiration().getTime() - System.currentTimeMillis(); if (expireTime 0) { jwtService.addToBlacklist(refreshToken, expireTime); } // 生成新的 refresh_token滚动刷新 String newRefreshToken jwtService.generateRefreshToken(user); return LoginResponse.builder() .accessToken(newAccessToken) .refreshToken(newRefreshToken) .expiresIn(jwtProperties.getAccessTokenExpire() / 1000) .build(); } }4. 前端无感刷新实现方案4.1 Axios 拦截器配置// authInterceptor.js import axios from axios; let isRefreshing false; let failedQueue []; const processQueue (error, token null) { failedQueue.forEach(prom { if (error) { prom.reject(error); } else { prom.resolve(token); } }); failedQueue []; }; // 创建 axios 实例 const api axios.create({ baseURL: /api, timeout: 10000 }); // 请求拦截器添加 access_token api.interceptors.request.use( config { const token localStorage.getItem(access_token); if (token) { config.headers.Authorization Bearer ${token}; } return config; }, error Promise.reject(error) ); // 响应拦截器处理 token 刷新 api.interceptors.response.use( response response, error { const originalRequest error.config; // 如果是 401 错误且不是刷新 token 的请求 if (error.response.status 401 !originalRequest._retry) { if (isRefreshing) { // 如果正在刷新将请求加入队列 return new Promise((resolve, reject) { failedQueue.push({ resolve, reject }); }).then(token { originalRequest.headers.Authorization Bearer ${token}; return api(originalRequest); }).catch(err Promise.reject(err)); } originalRequest._retry true; isRefreshing true; const refreshToken localStorage.getItem(refresh_token); if (!refreshToken) { // 没有 refresh_token跳转到登录页 window.location.href /login; return Promise.reject(error); } return new Promise((resolve, reject) { axios.post(/api/auth/refresh, { refreshToken }) .then(response { const { accessToken, refreshToken: newRefreshToken } response.data; // 更新本地存储的 token localStorage.setItem(access_token, accessToken); localStorage.setItem(refresh_token, newRefreshToken); // 更新 Authorization header api.defaults.headers.common.Authorization Bearer ${accessToken}; originalRequest.headers.Authorization Bearer ${accessToken}; // 处理队列中的请求 processQueue(null, accessToken); // 重试原始请求 resolve(api(originalRequest)); }) .catch(err { // 刷新失败清空本地存储并跳转到登录页 localStorage.removeItem(access_token); localStorage.removeItem(refresh_token); processQueue(err, null); window.location.href /login; reject(err); }) .finally(() { isRefreshing false; }); }); } return Promise.reject(error); } ); export default api;4.2 Token 存储策略前端 Token 存储需要考虑安全性和持久化// tokenManager.js class TokenManager { // 使用 localStorage 存储持久化但存在 XSS 风险 static setTokens(accessToken, refreshToken) { localStorage.setItem(access_token, accessToken); localStorage.setItem(refresh_token, refreshToken); } // 或者使用 httpOnly cookie更安全但需要后端配合 static setTokensAsCookie(accessToken, refreshToken) { document.cookie access_token${accessToken}; path/; max-age1800; Secure; SameSiteStrict; document.cookie refresh_token${refreshToken}; path/; max-age604800; Secure; SameSiteStrict; } static clearTokens() { localStorage.removeItem(access_token); localStorage.removeItem(refresh_token); // 清除 cookie document.cookie access_token; path/; expiresThu, 01 Jan 1970 00:00:00 GMT; document.cookie refresh_token; path/; expiresThu, 01 Jan 1970 00:00:00 GMT; } static getAccessToken() { return localStorage.getItem(access_token); } static getRefreshToken() { return localStorage.getItem(refresh_token); } }5. 安全防护与最佳实践5.1 JWT 安全配置要点安全措施配置方式防护目的强密钥至少 256 位随机字符串防止密钥破解合适的有效期access_token: 15-30分钟refresh_token: 7-30天平衡安全与体验HTTPS 传输生产环境强制 HTTPS防止中间人攻击黑名单机制Redis 存储失效 Token即时撤销 Token单设备登录存储最新 refresh_token防止多设备同时登录5.2 防止 Token 泄露的措施// SecurityConfig.java Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf().disable() // 根据前端框架选择是否禁用 .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/auth/refresh).permitAll() .anyRequest().authenticated() .and() .addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); } // 添加安全响应头 Bean public FilterRegistrationBeanCorsFilter corsFilter() { UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); CorsConfiguration config new CorsConfiguration(); config.setAllowCredentials(true); config.addAllowedOrigin(https://yourdomain.com); // 限制域名 config.addAllowedHeader(*); config.addAllowedMethod(*); source.registerCorsConfiguration(/**, config); FilterRegistrationBeanCorsFilter bean new FilterRegistrationBean(new CorsFilter(source)); bean.setOrder(Ordered.HIGHEST_PRECEDENCE); return bean; } }5.3 生产环境配置建议# application-prod.yml jwt: secret: ${JWT_SECRET:default-prod-secret-key} # 从环境变量读取 access-token-expire: 900000 # 15分钟 refresh-token-expire: 604800000 # 7天 spring: redis: host: ${REDIS_HOST:redis-server} port: ${REDIS_PORT:6379} password: ${REDIS_PASSWORD:} ssl: true # 生产环境启用 SSL # 日志配置记录认证相关操作 logging: level: com.example.jwtauth.service: DEBUG com.example.jwtauth.filter: DEBUG6. 常见问题排查与解决方案6.1 Token 相关错误排查表问题现象可能原因检查方式解决方案401 Unauthorizedaccess_token 过期或无效检查 Token 有效期和签名使用 refresh_token 刷新刷新接口返回 400refresh_token 无效或黑名单检查黑名单和 Token 绑定重新登录获取新 Token多设备登录互踢单设备登录机制生效检查 refresh_token 绑定设计合理的多设备策略Redis 连接失败配置错误或网络问题检查 Redis 服务状态验证配置和网络连通性6.2 性能优化建议// 使用 Redis 管道批量操作黑名单 public void batchAddToBlacklist(ListString tokens, long expireTime) { redisTemplate.executePipelined(new RedisCallbackObject() { Override public Object doInRedis(RedisConnection connection) throws DataAccessException { for (String token : tokens) { String key blacklist: DigestUtils.md5DigestAsHex(token.getBytes()); connection.setEx(key.getBytes(), expireTime / 1000, 1.getBytes()); } return null; } }); } // 使用本地缓存减少 Redis 访问 Component public class TokenCache { Autowired private RedisTemplateString, Object redisTemplate; private final CacheString, Boolean blacklistCache Caffeine.newBuilder() .expireAfterWrite(10, TimeUnit.MINUTES) .maximumSize(10000) .build(); public boolean isTokenBlacklisted(String token) { String cacheKey DigestUtils.md5DigestAsHex(token.getBytes()); return blacklistCache.get(cacheKey, key - { String redisKey blacklist: key; return redisTemplate.hasKey(redisKey); }); } }6.3 监控与日志记录// 添加详细的认证日志 Slf4j Service public class AuthService { public LoginResponse login(LoginRequest request) { // ... 登录逻辑 log.info(User {} logged in successfully, issued tokens with expiration: access{}, refresh{}, user.getUsername(), accessExpire, refreshExpire); return response; } public void logout(String refreshToken) { Claims claims jwtService.parseToken(refreshToken); Long userId claims.get(userId, Long.class); // 加入黑名单 long expireTime claims.getExpiration().getTime() - System.currentTimeMillis(); jwtService.addToBlacklist(refreshToken, expireTime); log.info(User {} logged out, token blacklisted with TTL {}ms, userId, expireTime); } }7. 扩展功能与进阶方案7.1 多设备登录管理如果需要支持多设备同时登录可以修改 refresh_token 存储策略// 支持多设备的 refresh_token 管理 public String generateRefreshToken(User user, String deviceId) { String refreshToken // ... 生成 token // 按设备存储 refresh_token String key refresh_token: user.getId() : deviceId; redisTemplate.opsForValue().set(key, refreshToken, jwtProperties.getRefreshTokenExpire(), TimeUnit.MILLISECONDS); return refreshToken; } // 获取用户所有设备的登录状态 public ListString getUserDevices(Long userId) { String pattern refresh_token: userId :*; SetString keys redisTemplate.keys(pattern); return keys.stream() .map(key - key.substring(key.lastIndexOf(:) 1)) .collect(Collectors.toList()); }7.2 权限细粒度控制在 JWT 中嵌入用户角色和权限信息public String generateAccessToken(User user) { SetString permissions userService.getUserPermissions(user.getId()); return Jwts.builder() .setSubject(user.getUsername()) .claim(userId, user.getId()) .claim(type, access) .claim(roles, user.getRoles()) .claim(permissions, permissions) // 添加权限信息 .setIssuer(jwtProperties.getIssuer()) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() jwtProperties.getAccessTokenExpire())) .signWith(SignatureAlgorithm.HS256, jwtProperties.getSecret()) .compact(); }7.3 分布式环境适配在微服务架构中需要考虑 Token 的验证和传播// 分布式 Token 验证服务 FeignClient(name auth-service) public interface AuthClient { PostMapping(/api/auth/validate) boolean validateToken(RequestHeader(Authorization) String token); PostMapping(/api/auth/userinfo) UserInfo getUserInfo(RequestHeader(Authorization) String token); } // 网关层统一认证 Component public class AuthFilter implements GlobalFilter { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String token extractToken(exchange.getRequest()); if (requiresAuth(exchange.getRequest()) !authClient.validateToken(token)) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } return chain.filter(exchange); } }这套 JWT 双令牌认证方案在实际项目中经过了充分验证能够有效平衡安全性和用户体验。关键是要根据具体业务需求调整 Token 有效期、黑名单策略和设备管理规则。在生产环境中还需要结合监控告警、日志审计等机制构建完整的安全防护体系。