1. 项目概述为什么JWT是无状态认证的“王牌”在微服务架构里认证授权是个绕不开的坎。上一期我们聊了Spring Security OAuth2那套基于Session或Redis Token的有状态方案虽然成熟但每次请求都得去中心化的存储里查一下令牌有效性对性能、对分布式会话管理都是个考验。所以当项目规模上去服务实例动不动就几十上百个的时候大家的目光自然就投向了无状态认证。而JWT就是实现无状态认证最主流、也最优雅的技术选型。JWT全称JSON Web Token你可以把它理解成一张“数字身份证”。它不像传统的Session ID那样只是个“钥匙”需要你拿着它去“保管箱”服务器存储里取用户信息。JWT本身就是“身份证”里面直接编码了用户的关键信息我们称之为Claims和防伪签名。服务端签发后客户端保存后续每次请求都带着它。任何服务实例拿到这个Token只需要用自己的密钥验一下签名确认这张“身份证”没被伪造、没过期就能直接信任里面携带的用户身份信息完全不需要再去查询任何中心化的存储。这就是“无状态”的精髓服务端不保存会话状态减轻了存储压力天然适合水平扩展。我经历过从有状态到无状态的迁移感触最深的就是排查问题的便利性和系统的吞吐量。以前用户报登录异常我们得连上Redis看Token还在不在、是不是被踢了现在直接看JWT里的过期时间exp和签发时间iat就行一目了然。性能上一次签名验证的消耗远小于一次网络IO加缓存查询。当然JWT也不是银弹它“一发不可撤销”的特性除非引入黑名单机制需要我们设计更短的令牌有效期并搭配刷新令牌Refresh Token来平衡安全与体验。接下来我们就深入这套机制的实战细节。2. 核心设计构建一个健壮的JWT认证授权体系单纯在登录接口里返回一个JWT字符串那只是“能用”离“好用”和“安全”还差得远。一个生产级的JWT认证体系需要从令牌结构、密钥管理、流程设计等多个层面进行周密考量。2.1 JWT令牌结构的三板斧一个JWT令牌由三部分组成用点号.分隔Header.Payload.Signature。我们重点看Payload也就是承载信息的部分。这里面的字段Claims选择大有讲究。标准声明Registered Claims这是JWT规范预定义的一些有特定含义的字段建议优先使用。sub主题通常放用户唯一标识如用户ID或用户名。exp过期时间这是个时间戳。这是安全的第一道防线必须设置一个合理的值比如2小时。iat签发时间用于计算令牌已使用了多久。iss签发者可以是你服务的名称在多系统环境下有助于区分令牌来源。公共声明Public Claims可以自定义一些业务通用字段但要防止命名冲突。私有声明Private Claims这是我们存放业务自定义信息的地方也是授权Authorization的关键。在授权时我们经常需要判断用户角色、权限。一种常见的做法是把用户角色列表如[ROLE_ADMIN, ROLE_USER]直接放在JWT的私有声明里比如一个叫authorities的字段。这样网关或资源服务解析JWT后就能直接拿到权限信息进行鉴权无需再查询用户数据库。注意切忌在JWT中存放敏感信息如密码明文、手机号等。因为JWT的Payload部分只是Base64编码并非加密任何人都可以解码查看。敏感信息必须加密后存放或坚决不放。2.2 密钥管理与签名算法选择签名是JWT防篡改的基石而签名依赖于密钥。密钥管理是安全的核心。对称加密 vs 非对称加密HS256HMAC SHA256对称加密签发和验证使用同一个密钥。简单高效但密钥一旦泄露攻击者可以签发任意令牌。适用于内部服务间通信或对安全要求不是极端苛刻的单体应用。RS256RSA SHA256非对称加密使用私钥签发公钥验证。公钥可以安全地分发给所有资源服务而私钥牢牢掌握在认证服务手中。即使资源服务被攻破攻击者也无法伪造新令牌。对于微服务架构强烈推荐使用RS256。密钥的存储与轮转私钥绝不能硬编码在代码或配置文件中提交到代码仓库。应该使用环境变量、配置中心如Nacos、Apollo或专门的密钥管理服务如HashiCorp Vault来注入。密钥需要定期轮转如每90天。设计时就要考虑支持多版本密钥共存为新签发的令牌使用新密钥同时旧密钥在一段过渡期内仍可用于验证旧令牌。2.3 双Token机制Access Token与Refresh Token这是平衡安全与用户体验的标准模式。Access Token生命周期短如2小时用于访问业务接口。它被直接放在JWT的Payload里。Refresh Token生命周期长如7天用于在Access Token过期后获取一对新的Token。它不包含用户权限信息本质上只是一个“兑换凭证”应该被安全地存储在服务端如数据库或缓存并关联用户ID和客户端信息。流程是这样的用户登录认证服务返回access_tokenJWT和refresh_token。前端用access_token调用接口。当access_token过期前端不是让用户重新登录而是用一个专用的刷新接口提交refresh_token来换取新的access_token和refresh_token。这样用户只在refresh_token也过期后才需要重新登录体验更流畅。同时服务端可以通过废弃某个refresh_token来强制用户重新登录实现了某种程度的“令牌吊销”。3. 实战搭建Spring Cloud Gateway Spring Security JWT理论说再多不如一行代码。我们以Spring Cloud Alibaba技术栈为例搭建一个完整的无状态认证流程。假设我们有三个核心服务认证服务auth-service、网关gateway、业务资源服务user-service。3.1 认证服务签发JWT令牌首先在auth-service中我们需要一个登录接口来处理凭证并生成JWT。1. 引入依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/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/version scoperuntime/scope /dependency2. 核心工具类JwtUtil这个类负责令牌的生成和解析。我们使用RS256算法。Component public class JwtUtil { // 从配置中心或环境变量读取这里示例从配置文件读 Value(${jwt.private-key}) private String privateKeyStr; Value(${jwt.public-key}) private String publicKeyStr; Value(${jwt.expiration:7200}) // 默认2小时 private Long expiration; private PrivateKey privateKey; private PublicKey publicKey; PostConstruct public void init() throws Exception { // 将Base64编码的字符串转换为RSA密钥对象 privateKey KeyFactory.getInstance(RSA) .generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(privateKeyStr))); publicKey KeyFactory.getInstance(RSA) .generatePublic(new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyStr))); } public String generateToken(String username, ListString authorities) { MapString, Object claims new HashMap(); claims.put(authorities, authorities); // 将权限列表放入claims // 也可以放其他业务字段如userId, deptId等 claims.put(username, username); return Jwts.builder() .setClaims(claims) // 设置私有声明 .setSubject(username) // 设置主题 .setIssuedAt(new Date()) // 签发时间 .setExpiration(new Date(System.currentTimeMillis() expiration * 1000)) // 过期时间 .signWith(privateKey, SignatureAlgorithm.RS256) // 使用私钥签名 .compact(); } public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(publicKey) // 使用公钥验证 .build() .parseClaimsJws(token) .getBody(); } // 验证令牌是否过期通常由解析器自动完成此方法可用于自定义检查 public boolean isTokenExpired(String token) { try { parseToken(token); return false; } catch (ExpiredJwtException e) { return true; } catch (Exception e) { // 其他解析异常也视为无效 return true; } } }3. 登录接口控制器RestController RequestMapping(/auth) public class AuthController { Autowired private AuthenticationManager authenticationManager; Autowired private JwtUtil jwtUtil; Autowired private RefreshTokenService refreshTokenService; // 假设的服务用于管理refresh token PostMapping(/login) public ResponseEntity? login(RequestBody LoginRequest request) { // 1. 使用Spring Security进行身份认证 Authentication authentication authenticationManager.authenticate( new UsernamePasswordAuthenticationToken(request.getUsername(), request.getPassword()) ); SecurityContextHolder.getContext().setAuthentication(authentication); // 2. 获取用户详情和权限 UserDetails userDetails (UserDetails) authentication.getPrincipal(); ListString authorities userDetails.getAuthorities().stream() .map(GrantedAuthority::getAuthority) .collect(Collectors.toList()); // 3. 生成JWT Access Token String accessToken jwtUtil.generateToken(userDetails.getUsername(), authorities); // 4. 生成并保存Refresh Token (这里简化实际需存库并关联用户) String refreshToken refreshTokenService.generateAndSaveRefreshToken(userDetails.getUsername()); // 5. 返回令牌 MapString, String tokens new HashMap(); tokens.put(access_token, accessToken); tokens.put(refresh_token, refreshToken); tokens.put(token_type, Bearer); tokens.put(expires_in, String.valueOf(jwtUtil.getExpiration())); // 秒数 return ResponseEntity.ok(tokens); } PostMapping(/refresh) public ResponseEntity? refresh(RequestBody RefreshRequest request) { // 1. 验证refresh token的有效性查库、是否被禁用等 String username refreshTokenService.validateRefreshToken(request.getRefreshToken()); if (username null) { return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Invalid refresh token); } // 2. 可选获取用户最新权限确保权限变更及时生效 ListString latestAuthorities userService.getAuthoritiesByUsername(username); // 3. 生成新的Access Token String newAccessToken jwtUtil.generateToken(username, latestAuthorities); // 4. 可选刷新refresh token本身实现滑动过期 String newRefreshToken refreshTokenService.refreshToken(request.getRefreshToken()); MapString, String tokens new HashMap(); tokens.put(access_token, newAccessToken); if (newRefreshToken ! null) { tokens.put(refresh_token, newRefreshToken); } return ResponseEntity.ok(tokens); } }3.2 网关服务统一鉴权与令牌转发网关是所有流量的入口在这里进行认证和鉴权是最合适的可以避免每个业务服务重复处理。1. 自定义全局过滤器我们在Spring Cloud Gateway中创建一个GlobalFilter来拦截请求。Component public class JwtAuthenticationFilter implements GlobalFilter, Ordered { Autowired private JwtUtil jwtUtil; // 网关也需要能解析JWT所以需要公钥 Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String path request.getURI().getPath(); // 1. 放行登录、刷新token等认证端点 if (path.startsWith(/auth/login) || path.startsWith(/auth/refresh) || path.startsWith(/public/)) { return chain.filter(exchange); } // 2. 从请求头获取Token String authHeader request.getHeaders().getFirst(Authorization); if (authHeader null || !authHeader.startsWith(Bearer )) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } String token authHeader.substring(7); // 去掉Bearer // 3. 验证并解析JWT Claims claims; try { claims jwtUtil.parseToken(token); } catch (ExpiredJwtException e) { // Token过期返回特定状态码方便前端刷新 exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); exchange.getResponse().getHeaders().add(X-Token-Expired, true); return exchange.getResponse().setComplete(); } catch (Exception e) { // 其他解析失败如签名错误、格式错误 exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 4. 将用户信息放入请求头传递给下游服务 String username claims.getSubject(); SuppressWarnings(unchecked) ListString authorities (ListString) claims.get(authorities); ServerHttpRequest mutatedRequest request.mutate() .header(X-User-Name, username) .header(X-User-Authorities, String.join(,, authorities)) // 权限用逗号分隔 .build(); // 5. 继续过滤器链 return chain.filter(exchange.mutate().request(mutatedRequest).build()); } Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE; // 设置高优先级尽早执行 } }2. 网关的JwtUtil网关只需要公钥来验证签名不需要私钥。所以它的JwtUtil可以简化只保留parseToken和isTokenExpired方法并且初始化时只加载公钥。3.3 资源服务基于请求头鉴权业务服务如user-service接收到网关转发来的请求已经包含了用户信息。我们只需要从请求头中取出信息并构建Spring Security的认证对象即可。1. 创建过滤器将网关传递的信息转换为AuthenticationComponent public class JwtHeaderAuthenticationFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头获取用户信息 String username request.getHeader(X-User-Name); String authHeader request.getHeader(X-User-Authorities); if (username ! null SecurityContextHolder.getContext().getAuthentication() null) { // 2. 构建权限列表 ListGrantedAuthority authorities Collections.emptyList(); if (authHeader ! null !authHeader.isEmpty()) { authorities Arrays.stream(authHeader.split(,)) .map(SimpleGrantedAuthority::new) .collect(Collectors.toList()); } // 3. 创建UsernamePasswordAuthenticationToken这里密码为null因为已认证 // 注意这里isAuthenticated设置为true因为网关已经完成了令牌的验证。 UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(username, null, authorities); // 4. 将认证信息放入SecurityContext SecurityContextHolder.getContext().setAuthentication(authentication); } filterChain.doFilter(request, response); } }2. 配置Spring Security在资源服务的配置类中注册上面的过滤器并配置安全规则。Configuration EnableWebSecurity public class ResourceServerSecurityConfig extends WebSecurityConfigurerAdapter { Autowired private JwtHeaderAuthenticationFilter jwtHeaderAuthenticationFilter; Override protected void configure(HttpSecurity http) throws Exception { http .csrf().disable() // 微服务内部API通常禁用CSRF .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 无状态 .and() .authorizeRequests() .antMatchers(/actuator/**).permitAll() // 监控端点放行 .antMatchers(/api/admin/**).hasRole(ADMIN) // 基于角色的访问控制 .antMatchers(/api/user/**).hasAnyRole(USER, ADMIN) .anyRequest().authenticated() // 其他所有请求都需要认证 .and() // 在标准的UsernamePasswordAuthenticationFilter之前添加我们的过滤器 .addFilterBefore(jwtHeaderAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); } }至此一个完整的、基于JWT的无状态认证流程就搭建起来了。用户登录auth-service获取双Token携带access_token访问业务接口请求经过gateway验证并转发用户信息最终user-service利用这些信息完成授权。4. 进阶议题与安全加固基础流程跑通只是第一步要上线生产环境还有一堆“坑”等着我们。4.1 令牌的安全存储与传输前端存储绝对不要用localStorage存TokenXSS攻击可以轻易读取它。推荐使用HttpOnly的Cookie来存储access_token这样JavaScript无法访问能有效防御XSS。对于refresh_token由于其生命周期长且用于关键操作可以考虑结合HttpOnly、Secure、SameSiteStrict等属性或使用后端Session存储但这就部分回到了有状态。传输始终使用HTTPS。Authorization头是标准做法。如果放在Cookie里务必设置Secure标志。4.2 实现JWT的“强制失效”黑名单机制JWT天然无法在有效期内被单个服务端失效这是它最大的缺点。为了应对令牌泄露、用户登出、密码修改等场景我们需要引入黑名单。思路在认证服务或网关维护一个黑名单缓存如Redis。当用户登出或管理员禁用用户时将此令牌的唯一标识JTIJWT ID或令牌签名或整个令牌存入Redis并设置过期时间略大于该令牌本身的exp。 在网关的认证过滤器中除了验证签名和过期时间增加一步检查当前令牌是否在黑名单中。签发时加入JTIString jti UUID.randomUUID().toString(); String token Jwts.builder() .setId(jti) // 设置唯一ID // ... 其他claims .compact();登出接口PostMapping(/logout) public ResponseEntity? logout(RequestHeader(Authorization) String authHeader) { String token extractToken(authHeader); Claims claims jwtUtil.parseToken(token); String jti claims.getId(); // 将jti加入Redis黑名单过期时间设置为 token剩余有效期 long ttl claims.getExpiration().getTime() - System.currentTimeMillis(); redisTemplate.opsForValue().set(blacklist:jti: jti, logged_out, ttl, TimeUnit.MILLISECONDS); return ResponseEntity.ok().build(); }网关过滤器增加黑名单检查// 在解析claims之后 String jti claims.getId(); if (Boolean.TRUE.equals(redisTemplate.hasKey(blacklist:jti: jti))) { exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); }实操心得黑名单会引入额外的Redis查询对性能有轻微影响。需要根据业务安全等级权衡。对于高并发场景可以只对高敏感操作如支付、修改密码进行强制黑名单校验普通查询可以放宽。4.3 动态权限更新与令牌刷新用户权限变更后旧的JWT在过期前依然有效因为权限信息已经编码在里面了。有两种解决思路缩短令牌有效期将access_token有效期设得很短如15分钟迫使前端频繁使用refresh_token获取新令牌。在刷新时从数据库读取用户的最新权限并编码到新令牌中。这是最常用的方法。权限中心实时查询在资源服务的每次授权判断时例如在PreAuthorize注解中不直接依赖JWT中的权限而是调用一个统一的权限服务接口进行实时验证。这种方法保证权限实时生效但增加了网络开销和系统复杂性。通常用于对权限实时性要求极高的金融或管理后台系统。4.4 监控与审计日志记录在网关和资源服务的关键点认证成功/失败、权限校验失败记录结构化日志包含用户ID、IP、请求路径、时间戳和结果。这对于安全审计和问题排查至关重要。指标收集监控认证失败率、令牌刷新频率、黑名单大小等指标异常波动可能预示着攻击或系统问题。令牌分析定期抽样解析JWT中的Claims分析令牌使用模式比如平均包含的权限数量、常见签发者等为优化系统提供数据支持。5. 常见问题排查与性能调优实录在实际部署和运维中你会遇到各种各样的问题。下面是我踩过的一些坑和解决方案。5.1 时钟偏移Clock Skew问题JWT的exp和iat校验依赖于服务器时间。如果认证服务和资源服务之间存在哪怕几秒钟的时钟不同步就可能导致“明明没过期却被判过期”或者“已经过期却被接受”的问题。解决方案在验证时允许一个小的时钟偏移容差Clock Skew。JJWT库支持这个配置。public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(publicKey) .setAllowedClockSkewSeconds(60) // 允许60秒的时钟偏移 .build() .parseClaimsJws(token) .getBody(); }更根本的解决办法是在所有服务器上部署NTP服务确保时间同步。5.2 令牌过长导致HTTP 413错误如果你在JWT的Payload里塞了太多信息比如把用户的完整菜单树都放进去编码后的字符串可能会非常长超过HTTP头或网关的默认大小限制。排查与解决精简Payload只放必要的身份标识sub,user_id和核心权限roles,perms。其他信息可以通过用户ID在资源服务中查询。调整服务器配置网关如Spring Cloud Gateway配置spring.codec.max-in-memory-size和spring.codec.max-request-header-size。Web服务器如Tomcat配置max-http-header-size。Nginx配置large_client_header_buffers。5.3 性能瓶颈分析与优化签名验证开销RS256非对称加密的验证开销比HS256对称加密大。在网关这种高并发入口大量验证操作可能成为CPU热点。优化使用性能更好的库如原生C库绑定或者对于内部完全可信的服务间通信可以考虑使用HS256并妥善保管密钥。也可以将公钥缓存在内存中避免每次验证都从文件或配置中心读取。黑名单查询开销每次请求都查一次Redis即使Redis再快也是网络IO。优化使用本地缓存如Caffeine缓存黑名单键设置一个较短的过期时间如1秒可以大幅减少对Redis的查询压力。采用布隆过滤器Bloom Filter进行前置过滤如果布隆过滤器说“肯定不在黑名单”就不需要查Redis能拦截绝大部分无效查询。网关单点压力所有认证逻辑都在网关网关挂了全站认证失效。优化网关集群部署并确保所有网关实例能访问到同一套公钥和黑名单缓存Redis集群。可以考虑将JWT验证逻辑下放到资源服务网关只做路由和转发但这会增加每个资源服务的复杂性和公钥分发成本。5.4 调试技巧如何查看和解析一个JWT开发过程中经常需要查看JWT里的内容。除了写代码解析还有一些小工具在线网站如 jwt.io 把Token贴进去能自动解析Header和Payload并验证签名如果你提供了公钥。浏览器插件如“JWT Debugger”等可以自动抓取请求中的JWT并解析。命令行使用base64解码。JWT的Header和Payload是Base64Url编码可以直接解码查看。# 假设你的token是 header.payload.signature echo eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 | base64 --decode # 输出: {alg:HS256,typ:JWT}注意千万不要用这种方式处理生产环境的真实Token尤其是通过不安全的网络传输。5.5 与其他微服务组件的集成问题Feign调用传递Token服务A通过Feign调用服务B时需要将当前请求的JWT传递给B。可以写一个FeignInterceptor从当前请求的上下文中获取Token并设置到Feign请求的Header里。Component public class FeignTokenInterceptor implements RequestInterceptor { Override public void apply(RequestTemplate template) { ServletRequestAttributes attributes (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); if (attributes ! null) { HttpServletRequest request attributes.getRequest(); String token request.getHeader(Authorization); if (token ! null) { template.header(Authorization, token); } } } }异步线程上下文丢失在异步任务或新线程中SecurityContext和请求上下文会丢失。你需要手动传递Token并在新线程开始时重新设置安全上下文。与Spring Cloud Gateway的CVE-2022-22947漏洞这个漏洞是Gateway的Actuator端点未授权访问导致RCE与JWT本身无关。但提醒我们必须保护好所有服务的Actuator端点和管理接口在生产环境要设置严格的访问控制或直接禁用不必要的端点。
