SpringCloud整合OAuth2.0实现微服务认证授权完整实战

做微服务的迟早会撞上认证授权这堵墙。单体应用时代大家习惯把用户登录态直接塞进Session再把Session丢给负载均衡后面的某一台机器反正请求大概率还会回到那台机器上。可一旦拆成SpringCloud的多个微服务服务之间要互相调用用户请求也会经过网关分发到不同实例这个时候“谁登录过、能不能调这个接口、用户信息怎么在服务间传递”就全成了问题。我在某公司做技术升级时正是被这个问题卡住最终用SpringCloud整合OAuth2.0把认证逻辑从各个业务服务里剥了出来统一收敛到独立的认证服务同时也解决了服务间调用无状态的信任问题。这篇内容适合正好在搭微服务、或者已经在微服务里被Session同步和接口鉴权折磨的团队参考。我会把设计方案、核心配置、实际编码踩过的坑都写出来尽量不说废话。读完你至少能搞清楚三件事OAuth2.0在微服务里到底扮演什么角色、认证服务和资源服务怎么在SpringCloud里落地、以及JWT这套方案里最容易出问题的几个环节到底怎么排查。1. 为什么微服务需要独立的认证中心1.1 分布式架构下的信任边界先聊一个基础问题为什么单体时代那套登录逻辑不能直接搬到微服务里。单体应用里用户登录后后端把用户信息写进Session浏览器记住SessionId后续请求带着这个ID到后端查Session就能识别身份。这个模型隐含一个前提应用只有一份Session数据就算存在内存里只要请求落到同一台机器就能查到。但微服务拆开之后每个服务独立部署可能各自占一个进程甚至一台机器Session数据放哪里就成了难题。有人把Session丢进Redis让所有服务共享这种方式能用但不够干净每个服务都要感知登录态的存在服务之间的调用也没有办法表达“我是代表哪个用户在处理这个请求”。我在项目里更倾向用另一种思路把认证这件事从业务服务里完全抽离出来专门的认证服务负责校验用户名密码、发放token业务服务只负责校验token、信任token里携带的用户信息。这个思路本质上是把信任边界划清楚——业务服务不再关心用户怎么登录的只关心请求里带的token是不是有效。这个模式配合SpringCloud就特别顺网关层或者各个资源服务统一校验token认证逻辑集中管理新增一个微服务也不需要重新写一套登录逻辑。1.2 用生活化类比理解OAuth2.0的四个角色OAuth2.0一开始容易让人觉得抽象后来我发现一个类比特别好使。你把它想成酒店入住用户是住客手机App是住客自己的手环真正的前台就是认证服务而各个业务服务就是酒店里的不同楼层。住客在App上完成身份登记登录前台发一张房卡token住客拿房卡去开自己楼层对应的房门调用资源服务。房门只认房卡不认人只要房卡能刷开就允许进入。这个模型里其实有四个参与方住客本人是资源所有者App是客户端前台是授权服务器房门是资源服务器。资源所有者、客户端、授权服务器、资源服务器这四个角色理解了OAuth2.0的流程基本就通了。客户端拿着资源所有者的授权去授权服务器换tokentoken再拿去资源服务器换数据。落到SpringCloud项目里客户端可能是前端网页、手机App也可能就是另一个后端服务授权服务器就是我们单独起的认证服务资源服务器是那些受保护的业务微服务。这套模型解决了核心问题资源服务器不需要保存任何登录状态只要它能验证token就够了。1.3 为什么选OAuth2.0而不是自己写拦截器有个很常见的想法是既然只是校验token那我写一套JWT工具在拦截器里解析就行了何必引入OAuth2.0这么大的东西。我承认这个想法有一定道理小项目确实可以这么干但一旦项目到了SpringCloud这种服务规模自己维护一套认证体系的成本会快速膨胀。自研方案要处理的问题包括token过期和刷新怎么设计、客户端凭证怎么管理、不同的调用方怎么区分权限等级、第三方系统接入时怎么对接授权流程。这些问题OAuth2.0协议早就定义好了标准接口和标准行为直接用就好。而且Spring生态里Spring Security OAuth2的体系非常完善TokenStore、ClientDetailsService、UserDetailsService这些核心接口都是现成的只要做配置和扩展不用从零造轮子。我在实际项目中见过自研认证系统后来因为各种需求演变搞得越来越臃肿最后还是要回归标准协议的情况。选OAuth2.0不是因为它新或者流行而是因为它是把“认证”这件事做标准化的成本最低路径。2. 技术选型为什么是OAuth2.0加JWT2.1 从Session到Token到底解决了什么这里面最本质的转变是认证状态从“服务端存储”变成了“客户端持有”。传统Session模式下认证状态存在服务器内存里服务端是有状态的这对水平扩展特别不友好。Token模式下认证的产物是一个字符串服务端不再存状态请求带着token过来服务端验证签名和有效期就算认证通过这种模式叫无状态认证。无状态这词听上去很技术实际理解起来很简单服务端不记你登没登录过只认你手里那张票是否有效。无状态带来的好处在微服务里是决定性的。每个服务都可以独立扩展不用共享任何Session存储服务之间互相调用的时候只要在请求里传递token接收方验证token就行不需要查数据库。这对网关层的路由转义、应对高并发时的水平扩缩容都有非常实质的帮助。我还见过某团队为了共享Session在Redis里存了海量用户状态每次扩容都要担心Redis集群压力换到Token方案后这些顾虑一下少了非常多。2.2 四种授权模式怎么选OAuth2.0协议里定义了授权码模式、简化模式、密码模式、客户端凭证模式四种授权模式。很多新手看到这四种模式容易头大其实只要分清场景就不乱。授权码模式适合有前端的Web应用比如浏览器网页前端先跳转到授权服务器用户登录后授权服务器通过回调URL把授权码给前端前端再用授权码换token。这个过程安全性高token不会直接暴露在前端地址栏。简化模式是授权码模式的精简版token直接通过URL回传安全性低一些现在我基本不建议用。密码模式适合我们自己平台内的客户端用户直接把自己的用户名密码交给客户端客户端拿着去换token。这种模式要求客户端是绝对可信的一般就是自家官方App或者自家后端。客户端凭证模式适合纯后端服务之间的调用不涉及用户就是服务以自己的身份去换token。在SpringCloud项目里用户登录走密码模式服务间调用走客户端凭证模式这两种组合覆盖了我经历过的绝大多数场景。2.3 选JWT还是传统Opaque TokenToken本身有两大类一类是不透明字符串存数据库一类是自包含的JWT。我这么说吧OAuth2.0协议并没有强制规定token必须是什么格式你可以用一个随机字符串存在Redis里也可以签一个JWT出来。区别在于不透明token需要资源服务器每次收到请求都回授权服务器或者Redis去验证多一次网络调用JWT则自带用户信息和过期时间资源服务器本地就能验签。微服务场景下我更偏好JWT关键是可以省掉token校验的网络往返。用户信息就放在token的payload里资源服务器解析出来直接就能用。代价是JWT一旦签发就没法在过期前主动吊销除非额外加黑名单机制这个问题后面我会重点讲。还有个容易被忽略的点JWT会越用越长如果一次把角色、权限、昵称、头像全塞进payload到后面每个请求都要背着这个超大token跑浪费带宽。我的习惯是payload里只放必要的用户ID、登录名、过期时间和少量基础信息其他数据服务需要时再查。3. 实操搭建认证服务与资源服务的完整落地过程3.1 工程结构和依赖准备先把最终的工程结构画出来。标准方案下要有认证服务和资源服务器两个角色网关在中间做路由转发。我这里说网关用SpringCloud Gateway认证服务是一个独立的SpringBoot应用业务微服务比如订单服务、用户服务作为资源服务器。工程上的划分是认证服务单独一个模块资源服务的依赖中引入spring-boot-starter-oauth2-resource-server认证服务引入spring-boot-starter-oauth2-authorization-server相关的适配包。老的spring-security-oauth2项目里大家习惯用EnableAuthorizationServer但新版SpringBoot里官方已经把它标记为过时我更推荐基于Spring Boot 3的Spring Authorization Server方案下面代码以这套为准。依赖层面我在某项目中用的版本是Spring Boot 3.2.x搭配Spring Cloud 2023.0.x认证服务的pom核心依赖如下dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdorg.springframework.security/groupId artifactIdspring-security-oauth2-authorization-server/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdmysql-connector-j/groupId artifactIdmysql-connector-j/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependencyRedis在这里不是必须的但建议加上后面做refresh token存储和JWT黑名单都方便。如果你公司里Redis运维成熟直接用Redis存已签发的refresh token能实现主动吊销一套完整的方案。3.2 授权服务器的核心配置Spring Authorization Server的配置重点集中在三个维度客户端信息、用户信息、token的生成与存储。先说客户端信息它描述的是“哪些应用有资格来换token”。比如前端Web应用、手机App、还有内部服务都要在这里注册给每个客户端分配clientId和clientSecret。这里我用内存配置演示生产环境要放到数据库里通过JdbcRegisteredClientRepository加载。Configuration EnableConfigurationProperties public class AuthorizationServerConfig { Bean Order(1) public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/oauth2/**, /login/**, /error) .authorizeHttpRequests(authorize - authorize .requestMatchers(/login/**).permitAll() .anyRequest().authenticated() ) .csrf(csrf - csrf.disable()) .exceptionHandling(ex - ex.defaultAuthenticationEntryPointFor( new LoginUrlAuthenticationEntryPoint(/login), new RequestHeaderRequestMatcher(X-Requested-With) )); return http.build(); } Bean public RegisteredClientRepository registeredClientRepository() { RegisteredClient webClient RegisteredClient.withId(UUID.randomUUID().toString()) .clientId(web-server) .clientSecret({noop}web-secret) .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC) .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .redirectUri(http://127.0.0.1:8080/login/oauth2/code/web-server) .scope(openid) .scope(user.read) .tokenSettings(TokenSettings.builder() .accessTokenFormat(OAuth2TokenFormat.SELF_CONTAINED) .accessTokenTimeToLive(Duration.ofHours(2)) .refreshTokenTimeToLive(Duration.ofDays(7)) .build()) .build(); RegisteredClient internalClient RegisteredClient.withId(UUID.randomUUID().toString()) .clientId(internal-service) .clientSecret({noop}internal-secret) .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC) .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) .scope(service.read) .build(); return new InMemoryRegisteredClientRepository(webClient, internalClient); } Bean public JWKSourceSecurityContext jwkSource() { RSAKey rsaKey generateRsaKey(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); } private static RSAKey generateRsaKey() { KeyPair keyPair generateRsaKeyPair(); RSAPublicKey publicKey (RSAPublicKey) keyPair.getPublic(); RSAPrivateKey privateKey (RSAPrivateKey) keyPair.getPrivate(); return new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(UUID.randomUUID().toString()) .build(); } private static KeyPair generateRsaKeyPair() { KeyPairGenerator keyPairGenerator null; try { keyPairGenerator KeyPairGenerator.getInstance(RSA); keyPairGenerator.initialize(2048); } catch (NoSuchAlgorithmException e) { throw new RuntimeException(e); } return keyPairGenerator.generateKeyPair(); } Bean public JwtDecoder jwtDecoder(JWKSourceSecurityContext jwkSource) { return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); } }这段代码里最关键的是JWKSource它负责管理RSA密钥对。授权服务器用私钥签发JWT资源服务器用公钥验签。生产环境千万不要每次启动都生成一对新密钥否则资源服务器缓存了旧的公钥后一旦认证服务重启所有已签发的token全部验签失败。正确做法是把RSA密钥持久化到配置中心或数据库里。再说用户信息的加载。授权服务器要能根据用户名查用户、校验密码、并加载角色权限。这个接口是UserDetailsService实际项目里就是从用户表查数据并封装成UserDetails。Spring Authorization Server对这块没有特殊要求按Spring Security的标准写法实现一个UserDetailsService就可以。Service public class UserDetailsServiceImpl implements UserDetailsService { private final UserAccountMapper userAccountMapper; public UserDetailsServiceImpl(UserAccountMapper userAccountMapper) { this.userAccountMapper userAccountMapper; } Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { UserAccount user userAccountMapper.findByUsername(username); if (user null) { throw new UsernameNotFoundException(用户不存在); } ListGrantedAuthority authorities userAccountMapper.findRolesByUserId(user.getId()) .stream() .map(SimpleGrantedAuthority::new) .collect(Collectors.toList()); return new User(user.getUsername(), user.getPassword(), authorities); } }密码的加密方式我直接用的委托密码编码器让不同的ClientDetails和用户密码能用不同算法做校验避免以后升级算法时旧的密码全部失效。这里给用户密码存的格式是{bcrypt}前缀加上密文。3.3 资源服务器的配置与实现资源服务器的任务就是验token、解token、拿用户信息。Spring Boot 3里配置一个资源服务器非常简单关键点在于配置JWT解码器时要指向授权服务器的JWK Set地址。资源服务器会通过这个地址获取公钥然后本地验签JWT。我在订单服务里加了一个最小的安全配置spring: security: oauth2: resourceserver: jwt: jwk-set-uri: http://auth-service:9000/oauth2/jwks对应的Java配置类Configuration EnableWebSecurity public class ResourceServerConfig { Bean public SecurityFilterChain resourceServerFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/api/**) .authorizeHttpRequests(authorize - authorize .requestMatchers(/api/public/**).permitAll() .requestMatchers(/api/order/**).hasRole(USER) .requestMatchers(/api/admin/**).hasRole(ADMIN) .anyRequest().authenticated() ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.jwtAuthenticationConverter(customJwtConverter())) ); return http.build(); } private ConverterJwt, ? extends AbstractAuthenticationToken customJwtConverter() { return jwt - { String username jwt.getClaimAsString(user_name); ListString scopes jwt.getClaimAsStringList(scope); ListGrantedAuthority authorities scopes.stream() .map(scope - new SimpleGrantedAuthority(SCOPE_ scope)) .collect(Collectors.toList()); return new JwtAuthenticationToken(jwt, authorities, username); }; } }很多新手会搞混资源服务器里的SCOPE_前缀和角色ROLE_前缀。OAuth2.0里scope是客户端申请的权限范围表示这个请求能访问什么资源更偏向客户端级别而角色是用户的角色属性更偏向用户级别。在配置authorizeHttpRequests时hasRole(USER)是检查角色hasAuthority(SCOPE_user.read)是检查scope。我刚做整合时在这个地方绕了好久一直以为配了scope就能控制用户权限实际两者是不同维度需要配合使用。3.4 网关层如何配合token验证SpringCloud Gateway在OAuth2方案里的定位不只是转发请求更合理的做法是在网关层做token的合法性校验然后剥离掉token把用户信息通过请求头下发给下游服务。这样下游服务不需要每个都配一套JWK校验逻辑网关就把脏活干完了。但要注意一个权衡如果业务服务有独立对外暴露的需求资源服务器那套安全配置还是要保留网关校验只能作为第一道关卡。我实际项目中网关的安全配置长这样spring: cloud: gateway: routes: - id: auth-service uri: lb://AUTH-SERVICE predicates: - Path/auth/** filters: - StripPrefix1 - id: order-service uri: lb://ORDER-SERVICE predicates: - Path/order/** filters: - StripPrefix1 - TokenRelayTokenRelay这个过滤器相当省心它会取当前用户上下文里的token自动加到转发请求头上。配合Spring Security的WebClient配置网关内部调用下游服务时token自然就带过去了。要是没有TokenRelay你得手动写global filter去解析token再放行繁琐且容易出错。3.5 完整调用链路的演示我把一条完整的链路走一遍这样你会更直观。前端用户访问登录页输入用户名密码认证服务校验通过返回一个access token和refresh token。前端拿着access token去请求订单服务获取订单列表请求路径是/order/api/list。网关拦截到这个请求后先通过TokenRelay把token转发给订单服务订单服务里配置的oauth2ResourceServer会校验token签名、有效期、scope。全部通过后controller里通过SecurityContextHolder获取当前登录用户信息GetMapping(/api/list) public ListOrderInfo listCurrentUserOrders() { Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); return orderService.listOrdersByUser(username); }这个流程走通之后你会发现整个系统没有任何一个接口是自己查Session的每个服务都只依赖token。后面不管加多少个微服务接入成本都只是加一份资源服务器配置。4. 常见问题与排查技巧实录4.1 token失效到底是在哪里断的JWT过期失效时前端反馈只是一句“登录已过期”但你到底该查认证服务、网关、还是资源服务这是有分层的。我建议先把问题拆成两个场景第一种是token签发后马上失效第二种是token用了一会儿才失效。前一种大概率是服务器时钟不同步授权服务器和资源服务器之间时间差过大导致签名验证时偏差了过期时间这个通过同步NTP能解决。后一种一般是access token本身的TTL设置太短需要根据业务容忍度调大我一般设置2小时配合7天有效的refresh token。还有个常见坑是JWT里iat时间问题。有一次某服务解析token总是报错查了半天发现是jwtDecoder和jwk-source之间没有对齐资源服务器拿到的公钥和授权服务器签发的私钥不是同一对。这个问题在授权服务器重启后特别容易出现因为密钥是随机生成的。解决起来就是刚才说的把RSA密钥持久化。4.2 授权码模式回调地址不匹配Spring Authorization Server对redirectUri的校验严格得很前端实际用的回调地址和RegisteredClient配置里登记的redirectUri只要有一点不一致就会报invalid redirect uri。这个报错很好认但新手容易被另一个问题误导。前端上的回调地址写的是http://localhost:8080注册时写的也是http://localhost:8080但浏览器实际访问的是http://127.0.0.1:8080。localhost和127.0.0.1在协议层面不是同一个host会直接校验失败。这个坑我踩过排查时只盯着字符串比对忘了浏览器地址栏显示什么才是真正的redirect。4.3 scope和authority的区别这个我前面提过但值得单列一条。scope表示客户端要求拿到的令牌权限范围是客户端申请的身份是SCOPE_前缀。authority是用户被授予的权限或角色属于用户身份的一部分角色是ROLE_前缀。配置接口权限时如果你用hasAuthority(SCOPE_user.read)那同一个用户不管通过哪个客户端来理论上只要有这个scope就能访问。如果你想控制一个用户能不能访问某个接口要用hasAuthority(ROLE_USER)。有时候一个接口既要求scope又要求角色需要and()把两个条件串起来。我在某项目里就是因为只配了scope没配角色导致所有登录用户都能调用admin接口好在测试环境就发现了。4.4 刷新token的逻辑和黑名单设计refresh token的主要作用是access token过期后客户端不需要再让用户重新登录通过refresh token换取新的access token。生产环境中refresh token不能没有但也不能无限期有效。我用的方案是refresh token存Redis7天有效期每次刷新时校验Redis里是否存在如果存在则删除旧的并生成新的access token和新的refresh token实现一种滑动的会话机制。这样做有个额外的好处用户修改密码或者管理员踢人时直接把Redis里的refresh token删掉就能让这个用户的会话在refresh token这个层面失效。有人说JWT无法吊销这说法其实不完整。JWT本身确实无法主动作废但你可以把access token的jti存到Redis里做黑名单每次请求校验时查一下黑名单。不过每个请求多一次Redis查询会对性能有影响所以我的做法是只对被强制登出的用户做这种处理普通用户正常走JWT无状态校验。4.5 密钥管理与多环境隔离密钥管理这事我放在最后讲因为它在生产环境爆发起来最致命。开发环境、测试环境、生产环境共用同一套RSA密钥表面看没什么问题但如果有服务A在测试环境调试时连的是生产环境的授权服务token一旦被复制出来就能在某些环境复用这个隐患很大。规范做法是每个环境独立密钥对通过配置中心按环境注入。密钥轮换也要设计好JWT方案里轮换密钥时要保证新旧密钥有一段重叠有效期资源服务器通过kid字段选择对应的公钥解码不然轮换瞬间大量请求会验签失败。我在项目里还遇到过一种场景资源服务器部署在多台机器上每台机器启动时并发去授权服务器拉JWK授权服务器压力突然飙高。这里要注意配置好资源服务器对jwks的缓存时间默认是5分钟一般不需要调整但如果你的服务实例特别多可以考虑把JWK Set接入配置中心而不是每次启动都全量拉取。5. 一个更直观的案例从零改造一个订单服务前面讲了不少配置类这一节我用一个改造案例把一个原本基于Session的老订单服务接入OAuth2.0。老代码里有一个拦截器从Session里拿用户然后放到ThreadLocal里controller从ThreadLocal取。这个逻辑在单体时代没毛病但订单服务后来独立部署用户登录信息在另一个服务里Session根本拿不到。改造的第一步是移除老拦截器引入资源服务器依赖写好JWK配置。第二步是把原来从ThreadLocal取用户的地方改成从SecurityContextHolder取。改完之后业务代码的侵入很小controller里的用户获取变成这样GetMapping(/list) public Result listOrders() { JwtAuthenticationToken token (JwtAuthenticationToken) SecurityContextHolder .getContext().getAuthentication(); String userId token.getToken().getClaimAsString(user_id); return Result.success(orderService.listByUserId(userId)); }第三步是处理内外网接口的差异。订单服务有一部分接口是内部服务之间调的比如库存服务需要回调订单状态这部分不能走用户token而是用客户端凭证模式。我给库存服务单独注册了一个internal-service客户端配置client_credentials授权模式调用订单服务时带上自己的client凭证换token订单服务只校验这个token的scope有没有internal:order。这样内部调用不依赖用户身份但依然在统一的鉴权体系内。改完这个服务最大的变化是以前登录状态在服务之间完全不可信现在每个请求必须带token才能进来而且这个token可以追踪到具体用户或具体应用。还有个变化是服务扩容时不用再考虑Session复制的问题新起的订单实例只要拉到公钥配置立刻就能处理请求。6. 我这套方案使用下来的实际感受记录几个自己在多次整合过程中总结出来的体会。第一技术选型上如果项目用的是Spring Boot 3尽早切换到Spring Authorization Server别在老项目里用已经被标记过时的starter后面升级会很痛苦。第二配置类不要写得过于分散把授权服务器配置、资源服务器配置、安全过滤器链拆成不同的配置类每个配置类职责单一不然出了权限问题你根本不知道改哪里。第三RSA密钥值管理从一开始就规范化千万别图省事每次启动生成这是我在真实项目里吃过亏的。还有一点值得说OAuth2.0整合到微服务里是一个持续演进的过程。第一版能把认证、授权、资源服务器跑通就已经解决70%的问题了剩下的30%集中在密钥轮换、单点登录、审计日志、动态权限这些细节。别指望一步到位先把基础链路跑顺再逐步强化安全细节。毕竟微服务架构里认证授权属于基础设施稳定比花哨重要得多。