微服务统一认证：JWT+网关全局鉴权体系

微服务统一认证JWT网关全局鉴权体系每个微服务都自己搞一套登录校验——这跟每个房间都装一把不同的锁有什么区别用户得带一大串钥匙。今天用 JWT 网关搞一套全局鉴权一锁通所有。一、微服务认证方案的演进单体应用时代用户登录后服务器在 Session 里存状态客户端带个 Cookie 就行。微服务化后这个模式碰到了问题Session Cookie 的困境 ┌─ order-service ─┐ 用户 ←→ 浏览器 ←→ 网关 ├─ product-service├ 谁都不认识谁的 Session └─ user-service ──┘ 问题1Session 存在单机内存其他服务访问不到 问题2即使共享 Redis Session跨域 Cookie 也是个坑 问题3服务间调用时下游不知道上游的用户身份1.1 三种方案对比方案原理优点缺点Session Cookie服务端存状态Cookie 传 sessionId可控性强、可主动踢人不适合分布式、跨域困难JWT推荐客户端存 Token自包含用户信息无状态、跨域友好、适合微服务无法主动失效、Token 体积大OAuth2第三方授权资源服务器分离适合开放平台复杂度高、学习曲线陡JWT 在微服务场景的优势无状态不需要集中式 Session 存储Token 本身就携带用户信息任何服务拿到 Token 都能独立校验。二、JWT 原理拆解JWTJSON Web Token长这样eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEsInJvbGUiOiJhZG1pbiJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c 拆开来看就是三段 Base64 编码用点号连接┌──────────────────────┬──────────────────────────┬─────────────────────────┐ │ Header │ Payload │ Signature │ ├──────────────────────┼──────────────────────────┼─────────────────────────┤ │ { │ { │ HMACSHA256( │ │ alg: HS256, │ userId: 1, │ base64(header) │ │ typ: JWT │ role: admin, │ . │ │ } │ exp: 1699999999 │ base64(payload), │ │ │ } │ secret │ │ │ │ ) │ └──────────────────────┴──────────────────────────┴─────────────────────────┘Header声明算法和类型HS256 HMAC-SHA256Payload存放声明claims比如用户 ID、角色、过期时间。Payload 只是 Base64 编码不是加密千万别放密码进去。Signature用 Header Payload 密钥算出签名防篡改。任何人改了 Payload签名就对不上了。校验流程服务器收到 JWT → 用同样的算法对 HeaderPayload 算签名 → 对比 Signature → 一致则信任 Payload。三、JWT 生成与解析jjwt引入 jjwt 库dependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-api/artifactIdversion0.12.3/version/dependencydependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-impl/artifactIdversion0.12.3/versionscoperuntime/scope/dependencydependencygroupIdio.jsonwebtoken/groupIdartifactIdjjwt-jackson/artifactIdversion0.12.3/versionscoperuntime/scope/dependencyJWT 工具类ComponentpublicclassJwtUtil{Value(${jwt.secret:MySecretKeyForJWT2024})privateStringsecret;Value(${jwt.access-token-expiration:1800})// 30 分钟privatelongaccessTokenExpiration;Value(${jwt.refresh-token-expiration:604800})// 7 天privatelongrefreshTokenExpiration;privateSecretKeygetSignKey(){returnKeys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));}// 生成 Access TokenpublicStringgenerateAccessToken(LonguserId,Stringrole){returnJwts.builder().subject(String.valueOf(userId)).claim(role,role).claim(type,access).issuedAt(newDate()).expiration(newDate(System.currentTimeMillis()accessTokenExpiration*1000)).signWith(getSignKey()).compact();}// 生成 Refresh TokenpublicStringgenerateRefreshToken(LonguserId){returnJwts.builder().subject(String.valueOf(userId)).claim(type,refresh).issuedAt(newDate()).expiration(newDate(System.currentTimeMillis()refreshTokenExpiration*1000)).signWith(getSignKey()).compact();}// 解析 TokenpublicClaimsparseToken(Stringtoken){returnJwts.parser().verifyWith(getSignKey()).build().parseSignedClaims(token).getPayload();}// 校验 Token 是否有效publicbooleanvalidateToken(Stringtoken){try{parseToken(token);returntrue;}catch(JwtException|IllegalArgumentExceptione){returnfalse;}}// 从 Token 中获取用户 IDpublicLonggetUserId(Stringtoken){returnLong.parseLong(parseToken(token).getSubject());}}四、统一鉴权架构用户 网关 微服务 ┌────────┐ ┌─────────────────────────┐ ┌──────────┐ │ 登录请求 │───→│ ① 校验用户名密码 │ │ │ │ │ │ ② 签发 JWT │ │ user- │ │ │←───│ ③ 返回 Token │ │ service │ └────────┘ └─────────────────────────┘ └──────────┘ │ ┌────────┐ ┌─────▼───────────────────┐ ┌──────────┐ │ 业务请求 │───→│ ④ 全局过滤器校验 JWT │ │ order- │ │(带Token)│ │ ⑤ 解析用户信息 │──→│ service │ │ │ │ ⑥ 透传用户信息到 Header │ │ │ └────────┘ └─────────────────────────┘ └──────────┘4.1 网关全局过滤器Spring Cloud Gateway 中实现全局 JWT 校验ComponentSlf4jpublicclassJwtAuthFilterimplementsGlobalFilter,Ordered{AutowiredprivateJwtUtiljwtUtil;// 不需要校验的路径白名单privatestaticfinalListStringWHITE_LISTArrays.asList(/api/user/login,/api/user/register,/api/public/);OverridepublicMonoVoidfilter(ServerWebExchangeexchange,GatewayFilterChainchain){Stringpathexchange.getRequest().getURI().getPath();// 白名单直接放行if(isWhitePath(path)){returnchain.filter(exchange);}// 从请求头获取 TokenStringtokenexchange.getRequest().getHeaders().getFirst(Authorization);if(tokennull||!token.startsWith(Bearer )){returnunauthorized(exchange,未携带Token);}tokentoken.substring(7);// 去掉 Bearer 前缀// 校验 Tokenif(!jwtUtil.validateToken(token)){returnunauthorized(exchange,Token无效或已过期);}// 解析用户信息LonguserIdjwtUtil.getUserId(token);ClaimsclaimsjwtUtil.parseToken(token);Stringroleclaims.get(role,String.class);// 将用户信息写入请求头透传给下游微服务ServerHttpRequestrequestexchange.getRequest().mutate().header(X-User-Id,userId.toString()).header(X-User-Role,role).build();log.debug(用户 {} 请求 {},userId,path);returnchain.filter(exchange.mutate().request(request).build());}privatebooleanisWhitePath(Stringpath){returnWHITE_LIST.stream().anyMatch(path::startsWith);}privateMonoVoidunauthorized(ServerWebExchangeexchange,Stringmessage){ServerHttpResponseresponseexchange.getResponse();response.setStatusCode(HttpStatus.UNAUTHORIZED);response.getHeaders().setContentType(MediaType.APPLICATION_JSON);Stringbody{\code\:401,\message\:\message\};DataBufferbufferresponse.bufferFactory().wrap(body.getBytes(StandardCharsets.UTF_8));returnresponse.writeWith(Mono.just(buffer));}OverridepublicintgetOrder(){return-100;// 高优先级在其他过滤器之前执行}}关键点用户信息通过自定义请求头透传。网关校验通过后把 userId 和 role 塞到X-User-Id和X-User-Role头里下游服务直接从请求头取就行不需要再解析 JWT。4.2 微服务端获取用户信息既然网关已经帮你解析好了下游服务直接取RestControllerRequestMapping(/api/order)publicclassOrderController{GetMapping(/my-orders)publicListOrdergetMyOrders(RequestHeader(X-User-Id)LonguserId){returnorderService.listByUserId(userId);}}更优雅的做法——自定义注解 参数解析器// 自定义注解Target(ElementType.PARAMETER)Retention(RetentionPolicy.RUNTIME)publicinterfaceCurrentUser{}// 参数解析器自动从请求头注入用户信息ComponentpublicclassCurrentUserResolverimplementsHandlerMethodArgumentResolver{OverridepublicbooleansupportsParameter(MethodParameterparameter){returnparameter.hasParameterAnnotation(CurrentUser.class);}OverridepublicObjectresolveArgument(MethodParameterparameter,ModelAndViewContainermavContainer,NativeWebRequestwebRequest,WebDataBinderFactorybinderFactory){HttpServletRequestrequestwebRequest.getNativeRequest(HttpServletRequest.class);LonguserIdLong.parseLong(request.getHeader(X-User-Id));Stringrolerequest.getHeader(X-User-Role);UserContextcontextnewUserContext();context.setUserId(userId);context.setRole(role);returncontext;}}// 使用GetMapping(/my-orders)publicListOrdergetMyOrders(CurrentUserUserContextuser){returnorderService.listByUserId(user.getUserId());}五、Token 刷新机制Access Token 设太长不安全泄露后风险期长太短用户体验差频繁登录。业界标准做法双 Token 机制。Access Token 过期 Refresh Token 过期 (30分钟) (7天) │ │ ────▼──────────────▶ 时间线 ──────────────────▼──── │ │ │ 正常使用 用 Refresh Token 需要重新登录 换取新 Access Token刷新接口实现PostMapping(/api/user/refresh)publicResultMapString,Stringrefresh(RequestParamStringrefreshToken){// 校验 Refresh Tokenif(!jwtUtil.validateToken(refreshToken)){thrownewBizException(Refresh Token 无效或已过期请重新登录);}ClaimsclaimsjwtUtil.parseToken(refreshToken);if(!refresh.equals(claims.get(type,String.class))){thrownewBizException(Token 类型错误);}// 检查 Refresh Token 是否在黑名单中已注销if(tokenBlacklistService.isBlacklisted(refreshToken)){thrownewBizException(Token 已注销请重新登录);}LonguserIdLong.parseLong(claims.getSubject());// 签发新的一对 TokenStringnewAccessTokenjwtUtil.generateAccessToken(userId,claims.get(role,String.class));StringnewRefreshTokenjwtUtil.generateRefreshToken(userId);// 旧的 Refresh Token 加入黑名单防止被恶意重复使用tokenBlacklistService.addToBlacklist(refreshToken,jwtUtil.getExpiration(refreshToken));MapString,StringtokensnewHashMap();tokens.put(accessToken,newAccessToken);tokens.put(refreshToken,newRefreshToken);returnResult.success(tokens);}六、Token 黑名单处理注销JWT 的最大软肋——无法主动失效。Token 发出去后在有效期内就是一张有效的通行证。解决方案用 Redis 维护一个黑名单登录时存进去网关校验时检查ServicepublicclassTokenBlacklistService{AutowiredprivateStringRedisTemplateredisTemplate;privatestaticfinalStringBLACKLIST_PREFIXjwt:blacklist:;// 加入黑名单TTL 设为 Token 剩余有效期publicvoidaddToBlacklist(Stringtoken,Dateexpiration){longttlexpiration.getTime()-System.currentTimeMillis();if(ttl0){redisTemplate.opsForValue().set(BLACKLIST_PREFIXtoken,1,ttl,TimeUnit.MILLISECONDS);}}publicbooleanisBlacklisted(Stringtoken){returnBoolean.TRUE.equals(redisTemplate.hasKey(BLACKLIST_PREFIXtoken));}}这样用户注销时把当前 Token 扔进黑名单网关校验时发现黑名单命中就直接拒绝。七、安全最佳实践Payload 不存敏感信息Payload 只是 Base64 编码不是加密。密码、手机号、身份证一律不往 Token 里塞密钥强弱决定安全高低HS256 场景下密钥至少 32 位随机字符。生产环境用 RS256非对称加密更安全全链路 HTTPSToken 在 HTTP 头里明码传输不用 HTTPS 等于裸奔Access Token 短时效15~30 分钟为宜。配合 Refresh Token 保证用户体验前端存储Web 端放 HttpOnly Cookie防 XSS移动端放 Keychain/Keystore。不要放 localStorage总结JWT 网关全局鉴权是微服务认证的黄金搭档——网关作为统一入口校验 Token、解析用户身份、透传给下游每个微服务无需重复写鉴权逻辑。配合双 Token 刷新和 Redis 黑名单安全性和用户体验兼得。