相信这两年折腾过认证授权的朋友都有同感Spring Boot 的 OAuth2 相关写法到了 3.X 版本之后几乎可以说是换了个人。老项目里那些基于 spring-security-oauth2 的EnableAuthorizationServer、EnableResourceServer 注解新项目里一个都见不到了取而代之的是 Spring Authorization Server 这个独立项目再加上 Spring Security 6 的组件式配置刚开始接触的时候确实有点找不着北。但 OAuth2 这个协议本身没有变变的只是实现方式和写法所以只要把认证服务和资源服务这两个核心角色的边界理清楚再跑通一条授权码模式的全流程后面的客户端模式、简化模式、Refresh Token 刷新就全都顺理成章了。这篇文章我打算直接把 Spring Boot 3.X 下搭建认证服务与资源服务的完整过程拆开讲从依赖选型、配置类写法、JWT 签名、客户端注册到资源服务器的令牌校验、scope 权限控制再到端到端联调和常见坑位排查都会覆盖到。适合正准备在 3.X 项目里落地 OAuth2或者从旧版迁移过来有点麻的同学参考。我会把每个关键配置背后的原理逻辑一并说清楚尽量做到既能直接抄作业也让你在看懂之后能根据自己项目的实际场景灵活调。1. 为什么 Spring Boot 3.X 的 OAuth2 值得重新学一遍1.1 组件换代从注解到 Starter 的转变先说一个很多从 2.X 时代过来的朋友最容易困惑的点。在旧的 Spring Boot 中想要快速搭一个授权服务器基本都是引入 spring-security-oauth2-autoconfigure然后在配置类上标注 EnableAuthorizationServer几行代码就能跑起来。但进入 Spring Boot 3 / Spring Security 6 时代这条路被彻底堵死了。官方把授权服务器Authorization Server从 Spring Security 中抽离出来交给了 Spring Authorization Server 这个独立项目维护并且提供了专门的 Starterspring-boot-starter-oauth2-authorization-server。这个转变的核心意义在于OAuth2 授权服务器的复杂度远高于普通的 Web 安全过滤链它涉及客户端注册、授权码管理、token 签发、JWT 签名、JWK 端点暴露、用户确认等一堆东西。把这些逻辑塞进 Spring Security 主项目里会让主项目变得臃肿难维护。抽出来之后Spring Security 主项目只负责 Resource Server资源验证和基础认证能力而授权服务器则按照自己的节奏独立演进比如对 PKCE、OIDC 的支持就更积极。在实际工程里这个拆分的体验是很好的因为资源服务的需求往往远多于认证服务而两者混在一起写容易造成依赖臃肿和配置混乱。还有一点必须注意Spring Boot 3.X 强制要求 JDK 17 及以上同时整个包名体系从 javax.* 换到了 jakarta.*。你在网上搜到的大量 Spring Boot 2.x 时代的 OAuth2 文章代码直接复制到 3.X 项目里大概率编译不过不是缺类就是兼容性问题排查起来还特别费劲。所以现在做 3.X 项目建议直接从 Spring Authorization Server 的官方文档或最新博客切入别再去翻那些老代码了。1.2 认证服务与资源服务分离的架构价值很多人第一次接触 OAuth2容易把认证服务和资源服务搞混或者干脆做成一个服务。其实这两个角色在协议层面是严格分离的。简单说认证服务Authorization Server负责你是谁、你能干什么的确认它管用户登录、客户端校验、授权码发放、令牌签发资源服务Resource Server负责你拿着的令牌能不能访问这个接口它从请求头解析 Bearer Token验签、看 scope、看过期时间通过之后才放行到具体的业务接口。为什么要拆开我用一个生活化的例子说明认证服务相当于小区门口的保安岗亭负责核实来人身份、登记访客信息、发放临时通行证资源服务则是小区内部各栋楼的单元门住户拿着通行证进出单元门只验证通行证是否有效并不需要关心这个人具体在保安岗亭里登记了什么。如果每一栋单元门都要自己去核实一次住户的完整信息效率太低而且一旦保安岗亭的设备升级所有单元门都得跟着改。所以 OAuth2 的设计就是让认证服务统一签发令牌资源服务只认令牌本身。落到实际项目里这个分离的收益非常明显。比如你手头同时有一个大学生就业推荐系统后台和一个面向招聘单位的多商户商城平台如果每个系统都单独做一套登录认证用户要在每个系统里各注册一次密码同步、会话管理都是麻烦事。把认证集中到一个服务里多个资源服务共同信任同一个令牌签发方就能实现一份令牌多处访问也方便做统一的用户管理和审计。我最近在整理基于 Spring Boot 的技术方案时发现不少多商户跨境电商这类需要开放 API 给第三方的项目也都在用 OAuth2 的客户端模式来给合作伙伴签发独立的访问令牌就是冲着认证和业务解耦这个好处去的。1.3 哪些项目适合用这套方案我先说说什么情况下别硬上 OAuth2。如果只是内部管理后台用户就几十个用 Session 登录或者简单的表单登录就足够了引入 OAuth2 反而增加了配置和运维成本。OAuth2 的典型适用场景是存在一个认证中心、多个受保护业务服务的结构或者需要开放 API 给第三方应用使用。举几个实际场景。第一个是微服务架构网关层、用户服务、订单服务、商品服务各自独立前端统一从认证服务拿 token再带着 token 访问各个业务服务最适合用资源服务器模式。第二个是前后端分离项目前端 SPA 应用通过授权码模式跟认证服务交互后端所有接口统一做 JWT 校验。第三个是开放平台比如我之前看过的多商户跨境商城系统商户需要调用平台 API 查询订单、同步库存平台可以先通过客户端模式给每个商户发放独立的 token商户带着 token 请求开放接口这样平台就能对每个商户的调用权限和频次做精细化管控。在这类项目里Spring Boot 3.X 加 Spring Authorization Server 的组合基本算是 Java 生态当前最正规的实现路径了。下面我就从零开始把认证服务和资源服务的具体搭建过程一步步展开。2. 认证服务搭建核心配置与实现细节2.1 工程初始化与注意事项我习惯用 Spring Initializr 创建两个独立的 Maven 工程一个命名 auth-server另一个命名 resource-server。在 Spring Boot 3.X 里认证服务需要引入的依赖很简单spring-boot-starter-oauth2-authorization-server 一个就覆盖了 Web 安全、OAuth2 授权服务器核心、JWT 编码、JWK 处理。另外我通常会额外引入 spring-boot-starter-thymeleaf 做登录页面和授权确认页面否则后续测试授权码模式时默认的页面会不太好用。第一次用这个 Starter 的时候有件事要特别提醒它并不像旧版那样自动覆盖所有端点很多默认行为需要靠显式配置来激活。比如授权端点 /oauth2/authorize 和令牌端点 /oauth2/token如果没配置好 SecurityFilterChain 的规则可能直接被历史遗留的登录逻辑给拦截掉表现为裸奔或者全部 401排查起来特别容易懵。所以认证服务的第一个配置类核心就是构建一条专用于 OAuth2 协议端点的过滤器链把授权端点、令牌端点、JWK 端点纳入管理同时放行浏览器需要直接访问的页面。server: port: 8080 spring: application: name: auth-server这里我故意把认证服务端口设为 8080资源服务稍后设为 8081这样我在演示联调时端口关系一目了然。如果你是用 VSCode 开发 Spring Boot 项目改端口无非就是修改 application.yml 里这一行重启后注意 IDE 的终端输出确认实际监听端口没被占用就行。之前有同学在 VSCode 调试时发现改了端口没生效十有八九是配置文件没被加载或者起了多个实例调试时看 Spring Boot Dashboard 面板更直观。2.2 授权服务器过滤器链配置认证服务的核心配置类我按 Spring Security 6 的风格用 Lambda 写法来设置。第一条过滤器链专门处理 OAuth2 协议本身相关端点包括 /oauth2/authorize、/oauth2/token、/.well-known/openid-configuration 等同时需要支持表单登录因为用户在浏览器上走授权码流程时得先登录才能做授权确认。Configuration EnableWebSecurity public class AuthorizationServerConfig { Bean Order(1) public SecurityFilterChain authServerSecurityFilterChain(HttpSecurity http) throws Exception { http.securityMatcher(/oauth2/**, /login/**, /.well-known/**) .authorizeHttpRequests(auth - auth .requestMatchers(/.well-known/**).permitAll() .anyRequest().authenticated()) .csrf(csrf - csrf.ignoringRequestMatchers(/oauth2/token)) .formLogin(form - form.loginPage(/login).permitAll()); return http.build(); } }绕不开的 Order(1) 这个注解它的排序逻辑对新手特别容易造成困惑。Spring Security 允许多个 SecurityFilterChain 并存匹配谁就看路径和顺序。授权服务器的协议端点优先级必须高于后续可能加的其他过滤链否则请求可能会先落到别的链里被处理后放行导致令牌端点的安全校验失效。我自己在写多租户项目时就在这个排序上栽过一次后来养成习惯只要配置多个 SecurityFilterChain永远把 OAuth2 协议链排在第一位。csrf 这块也值得展开说。令牌端点按 OAuth2 规范要求处理 client_id 和 client_secret 时使用 Basic Auth对 CSRF 令牌的校验会造成干扰所以 /oauth2/token 必须忽略 CSRF。但 /oauth2/authorize 是走浏览器跳转的 GET 请求如果前端页面有表单提交授权确认通常建议保留 CSRF 保护除非确认客户端不会跨站请求再考虑放行。2.3 注册客户端scope、回调地址与授权模式授权服务器的另一个核心配置是 RegisteredClientRepository相当于哪些应用可以使用我的认证服务的注册表。最轻量的是 InMemoryRegisteredClientRepository适合学习和中小型项目生产环境建议换成基于 JDBC 的 JdbcRegisteredClientRepository保存到数据库里方便动态管理客户端。我先把内存版跑通Bean public RegisteredClientRepository registeredClientRepository() { RegisteredClient authServerClient RegisteredClient.withId(auth-server-client) .clientId(demo-client) .clientSecret({noop}demo-secret) .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) .redirectUri(http://127.0.0.1:8081/login/oauth2/code/demo-client) .scope(message.read) .scope(message.write) .scope(openid) .clientSettings(ClientSettings.builder().requireAuthorizationConsent(true).build()) .tokenSettings(TokenSettings.builder() .accessTokenTimeToLive(Duration.ofMinutes(30)) .refreshTokenTimeToLive(Duration.ofDays(1)) .build()) .build(); return new InMemoryRegisteredClientRepository(authServerClient); }clientId 是客户端唯一标识clientSecret 是客户端密码。这里我特意写了 {noop} 前缀表示明文存储演示阶段方便生产环境一定换成 BCrypt 之类的方式再注册或者直接把密文存进数据库。授权模式这里我一次性加了授权码、刷新令牌、客户端模式三种最常见的三类需求全部覆盖。回调地址必须跟资源服务实际配置的 redirect-uri 完全一致否则会被 Spring Authorization Server 直接拒绝而且报错信息往往不太直观出现 invalid redirect_uri 时报错就得往这上面查。scope 的设计直接影响资源服务的接口权限粒度。比如 message.read 和 message.write 两个 scope分别对应只读接口和写接口权限资源服务在接口上做权限判断时这些 scope 会被依次塞进 JWT 的 scope 声明里。所以不要把所有接口都用一个 scope 糊过去否则后面做接口分级授权会很痛苦。requireAuthorizationConsent(true) 表示每次授权都需要用户在确认页面上点击同意不设置的话默认可能直接跳过程序确认步骤后面的授权码流程演示我就保留它方便把整个交互链路看清楚。2.4 用户存储从内存用户到数据库用户授权服务器要做的第一件事是认人所以还得配置一个 UserDetailsService。最简单的方式是内存用户注册一个账号用于登录测试Bean public UserDetailsService userDetailsService() { UserDetails admin User.withUsername(admin) .password({noop}123456) .roles(ADMIN) .build(); return new InMemoryUserDetailsManager(admin); } Bean public PasswordEncoder passwordEncoder() { return PasswordEncoderFactories.createDelegatingPasswordEncoder(); }passwordEncoder 这里其实就是用 Spring Security 5 以后推荐的双委托方式默认支持一种带前缀的编码策略。演示时 {noop} 表示 NoOpPasswordEncoder明文比对别用在生产环境。如果项目里有现成的用户表可以通过实现 UserDetailsService 接口注入 Mapper 查询用户再把查询结果转换成 UserDetails这就是把认证服务接入自家用户体系的标准路径。有一点容易被忽略授权服务器里的这个用户体系和资源服务器里的用户体系常常是两回事。认证服务关心的是用户名密码对不对资源服务关心的是JWT 里的 claim 和 scope 够不够。前者归认证服务管后者在令牌解析后自然获得不需要资源服务再次查数据库。2.5 JWT 签名密钥与 JWK 端点授权服务器签发的 JWT必须用私钥签名资源服务器再用公钥验签。这个私钥签名、公钥验签的关系是整个 OAuth2 JWT 安全模型的地基。Spring Authorization Server 通过 JWKSource 接口来管理密钥默认配置会从环境里找一个 key没有的话就得自己生成 RSA 密钥并注册进去。我的生成逻辑是这样的Bean public JWKSourceSecurityContext jwkSource() { RSAKey rsaKey generateRsaKey(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); } private static RSAKey generateRsaKey() { try { KeyPairGenerator keyPairGenerator KeyPairGenerator.getInstance(RSA); keyPairGenerator.initialize(2048); KeyPair keyPair keyPairGenerator.generateKeyPair(); RSAPublicKey publicKey (RSAPublicKey) keyPair.getPublic(); RSAPrivateKey privateKey (RSAPrivateKey) keyPair.getPrivate(); return new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(UUID.randomUUID().toString()) .build(); } catch (NoSuchAlgorithmException e) { throw new RuntimeException(RSA 密钥生成失败, e); } }keyID 非常重要。JWT 的请求头中会携带 kid资源服务器与认证服务器通过 JWK 端点同步公钥时靠 kid 区分不同时期的签名密钥。如果你用固定的 keyID在密钥轮换的场景下资源服务器会拿到过期的公钥去验签结果就是验签失败。生产环境建议用一个固定的 RSA 密钥字符串配置在 yml 里方便多实例部署时保持一致而不是每次启动都随机生成。有了 JWKSourceSpring Authorization Server 会自动暴露一个 JWK Set 端点默认路径是 /.well-known/jwks.json。这个端点会把公钥信息以 JSON 格式公开出去资源服务器通过它获取验签公钥。如果资源服务器配置的是 issuer-uri 方式还会自动去 /.well-known/openid-configuration 发现这个 JWK 端点的地址。3. 资源服务搭建JWT 解析与接口权限控制3.1 依赖与最小配置资源服务器的工程依赖就更清爽了只需要 spring-boot-starter-web 和 spring-boot-starter-oauth2-resource-server加上 spring-security-config 也会被自动传递引入。不需要额外引入 Authorization Server 相关依赖因为 JWT 验签逻辑并不需要完整的授权服务器功能。server: port: 8081 spring: application: name: resource-server security: oauth2: resourceserver: jwt: issuer-uri: http://localhost:8080最关键的就是 issuer-uri 这一行。它告诉资源服务器我信任 http://localhost:8080 这个认证服务你从它那里发现 JWK 端点、验签公钥。启动资源服务后Spring Security 会对这个地址发起发现请求拿到 jwks_uri并定时刷新公钥缓存。这也是资源服务能快速校验令牌的关键因为它不需要每次请求都去认证服务问一次本地缓存公钥直接验签即可。如果你要调试时临时改端口比如把认证服务从 8080 改成 8082resource-server 里的 issuer-uri 也必须同步改否则验签会因为 issuer 不匹配直接失败。很多同学在 VSCode 里同时开两个 Spring Boot 项目时容易忽略这个联动关系批次启动后看到 401 一脸茫然其实先看两个配置文件里的端口对不对能少走很多弯路。3.2 资源服务过滤器链与 JWT 校验资源服务的 SecurityFilterChain 写法也很固定关键在于 oauth2ResourceServer(oauth2 - oauth2.jwt()) 这一段。它把默认的 JwtDecoder 接入了过滤器链每次请求进来都会自动解析 Authorization 请求头里的 Bearer Token如果令牌没有、格式错误、签名不对、过期、issuer 与预期不符都会返回 401。Configuration EnableWebSecurity public class ResourceServerConfig { Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http.authorizeHttpRequests(auth - auth .requestMatchers(/public/**).permitAll() .requestMatchers(/api/messages).hasAuthority(SCOPE_message.read) .anyRequest().authenticated()) .oauth2ResourceServer(oauth2 - oauth2.jwt()); return http.build(); } }这里有两个细节值得展开。第一个是 hasAuthority(SCOPE_message.read)Spring Security 在解析 JWT 时会自动把 JWT 中的 scope 或 scp 声明转换成权限且每个权限自动加 SCOPE_ 前缀所以你写权限判断时一定别漏掉这个前缀。第二个是 oauth2ResourceServer 也是可以配置表单登录同时保留接口令牌认证之类混合模式的不过初学阶段不建议搞混合认证服务是认证服务、资源服务是资源服务一条链路最好。如果认证服务返回的 JWT 中声明名不是标准的 scope而是比如 authorities、roles 等自定义名称也可以在配置类里自定义 JwtAuthenticationConverter。后面等整个流程跑通我再展开说明。3.3 接口层拿到用户信息与 scope 判断资源服务里最常见的操作就是从 JWT 中取出当前用户信息再决定接口返回什么。Spring Security 直接把解析好的 Jwt 对象注入进来由于 JWT 经过签名所以资源服务完全信任这里面携带的信息不需要再调用认证服务去查用户。RestController public class MessageController { GetMapping(/api/messages) public String getMessages(AuthenticationPrincipal Jwt jwt) { return Hello jwt.getSubject() , access_token expires at: jwt.getExpiresAt() , scopes: jwt.getClaimAsStringList(scope); } }getSubject() 默认对应认证后用户的标识。授权码模式下subject 是登录用户的 username 或者用户在认证服务侧的唯一 id。客户端模式下subject 通常就是 clientId。所以业务接口如果需要谁在调用我这个信息读 subject 是最直接的方案。如果你还想看更多 claim比如用户名、邮箱、部门 id只需要在生成 token 的时候往 JWT 里塞就行。Spring Authorization Server 提供了自定义 OAuth2TokenCustomizer可以在 token 生成前动态往 claims 里追加信息。后面讲扩展的时候我会给出一个例子这个非常实用。资源服务还可以用 PreAuthorize(hasAuthority(SCOPE_message.write)) 来给具体方法做更细粒度的权限控制只要在配置类上加 EnableMethodSecurity 注解即可。这样接口层和配置层的权限控制就能结合使用大面上的路径规则放配置里精细权限放方法注解上各司其职。4. 端到端联调把四种流程跑通一遍4.1 授权码模式全流程实测这是整个 OAuth2 体系里最难理解、也最核心的一个流程。我建议你手边把 auth-server 和 resource-server 两个项目都启动起来跟着我一步步操作。第一步浏览器访问授权端点http://localhost:8080/oauth2/authorize?client_iddemo-clientresponse_typecodescopemessage.readredirect_urihttp://127.0.0.1:8081/login/oauth2/code/demo-client这个时候因为没有登录Spring Security 会把你重定向到 /login 页面输入 admin / 123456 后就进入到了一个授权确认页面页面上会显示客户端 demo-client 想要申请 message.read 权限。点击同意之后浏览器地址栏会带着一个 code 参数重定向到http://127.0.0.1:8081/login/oauth2/code/demo-client?codexxxx注意这个 code 是一次性的且有效期只有几十秒。拿到 code 之后客户端后端或者 Postman 就可以拿它去令牌端点换 token 了。这里我直接用 curl 演示curl -X POST http://localhost:8080/oauth2/token \ -u demo-client:demo-secret \ -d grant_typeauthorization_code \ -d codexxxx \ -d redirect_urihttp://127.0.0.1:8081/login/oauth2/code/demo-client返回的 JSON 里会有 access_token、refresh_token、expires_in 等字段。拿到 access_token 后访问资源服务curl -H Authorization: Bearer eyJraWQ... http://localhost:8081/api/messages如果一切正常接口会返回 Hello admin 加上一串 JWT 元信息。我建议你把返回的 JWT 粘到 jwt.io 上去解析看看能看到签名算法、kid、issuer、scope 等字段理解瞬间会深很多。授权码模式的好处是用户密码永远不会暴露给第三方应用第三方通过授权码换 token相当于拿了一张临时凭证这也是它成为 Web 应用最主流授权模式的原因。整个流程中我最想强调一个概念转发 code 这一步只能在客户端后端到认证服务之间发生不能在浏览器里用 JS 直接操作。因为 cookie 和 CORS 的限制SPA 直接搞授权码模式会比较痛苦所以才有了后面补充的 PKCE 增强变体本质是对无后端服务器场景的授权码流程加了动态验证。初学阶段先把带客户端的完整流程跑通再考虑 PKCE。4.2 客户端模式适合服务间调用客户端模式是整个 OAuth2 授权模式里最简单的一张图能说清客户端直接拿 clientId 和 clientSecret 去 token 端点换 token没有用户参与、没有跳转、没有 code。curl -X POST http://localhost:8080/oauth2/token \ -u demo-client:demo-secret \ -d grant_typeclient_credentials \ -d scopemessage.read这个模式适合服务间通信比如批量任务调度服务调用订单服务接口数据库同步服务调用商品服务接口等。因为调用双方都是后端服务天然信任度高也不涉及用户同意环节。在多商户跨境电商场景里平台给商户分配 API 密钥本质上就是用了客户端模式商户通过 clientId 和 clientSecret 获取属于自己的 token再访问平台开放的接口。这个 token 里没有用户身份只有哪个客户端在调用这个信息所以 clientId 就成了识别调用主键。但要提醒一点client_credentials 模式下 token 不会过期得很快默认 30 分钟而且签发逻辑一般不关心用户状态。如果商户被平台停用了光删掉数据库里的 client 记录不够已经签发的 token 在过期前仍然有效。生产环境可以考虑把 token 有效期缩短同时在资源服务层配合黑名单机制做实时生效的封禁控制。4.3 Refresh Token 刷新与资源服务验签的关系access_token 有效期短refresh_token 有效期长是 OAuth2 的典型设计。刷新流程如下curl -X POST http://localhost:8080/oauth2/token \ -u demo-client:demo-secret \ -d grant_typerefresh_token \ -d refresh_tokenxxxx刷新成功后返回一组新的 access_token 和 refresh_token。资源服务不需要关心刷新动作它只验证 access_token 本身是否有效。如果令牌过期返回 401前端收到 401 后自动拿 refresh_token 去换新 token再重放一次请求。我在实际项目里见过不少直接把 access_token 有效期设成 7 天、30 天的写法省事是真省事但安全风险也大一旦 token 泄漏攻击者可以长时间使用。我一般建议 access_token 控制在 15 到 30 分钟refresh_token 设 1 到 7 天再配合 refresh token 轮换策略补偿用户体验。5. 常见问题排查与调试技巧实录5.1 高频问题速查表我把实际开发和迁移过程中最容易碰到的几个问题整理成了一个表每个问题都是我或身边同事至少踩过一遍才总结出来的照着核对比自己白查半天靠谱得多。现象可能原因解决办法访问授权端点直接 404securityMatcher 没匹配到 /oauth2/**检查 Order(1) 和安全过滤链路径是否正确拿到 code 换 token 报 invalid_grantcode 过期、一次性已消耗、redirect_uri 不一致重新走一次授权流程确认回调地址完全一致授权端点提示 Unsupported response_type授权码模式需要 response_typecode检查授权请求 URL 参数拼接资源服务返回 401 invalid_tokenissuer-uri 不匹配或公钥不同步核对认证服务的地址重启资源服务刷新 JWK 缓存资源服务接口提示 Access Deniedscope 前缀写错少写了 SCOPE_确认 hasAuthority(SCOPE_message.read) 带上了 SCOPE_ 前缀登录页面样式丢失模板资源路径被 Security 拦截用 permitAll 放行静态资源目录多个 SecurityFilterChain 配置出错顺序问题导致请求被错误的链处理把 OAuth2 协议链放到 Order(1)JWT 解析后 scope 为空客户端没有申请该 scope 或 token 生成时未带入检查客户端注册的 scope 清单和授权请求参数client_secret 密码错误难排查{noop} 明文存储时容易看错字符先用 PasswordEncoder 工具类生成密文再存储我在第一次把 2.x 项目往 3.X 迁移时困扰最久的就是 invalid_token 问题。旧项目里资源配置方式全变了新项目里 issuer-uri 一旦配置得和认证服务的实际地址对不上就是反复 401而日志里又不会直接告诉你说 issuer 不匹配。后来我把资源服务启动日志里的 JwtDecoder 初始化过程完整打出来发现它默认会对 http://localhost:8080/.well-known/openid-configuration 做一次请求。你可以用浏览器直接访问这个端点如果返回了 JSON说明认证服务本身的发现端点没问题问题就出在资源服务侧的公钥缓存或配置连接上。5.2 调试心得从日志和信任链两个维度入手OAuth2 链路出错最忌讳的就是变着法子改配置碰运气。我自己的习惯是分两步走第一步先判断是协议流程没走对还是资源服务验签没过。比如用 curl 直接请求 token 端点能拿到 token那协议流程大概率没问题直接看资源服务日志如果 token 端点本身就报错那就按授权码流程逐步拆解。第二步把资源服务启动时的密钥发现日志打开确认它从认证服务同步到了正确的公钥。你可以给 application.yml 加日志配置logging: level: org.springframework.security.oauth2: DEBUG开了 debug 之后JwtDecoder 会打出解析 token 时的详细过程和验签结果。看到类似 JWT validation failed: Invalid issuer 这种日志基本就能锁定是 issuer-uri 配置的问题。要看到 JWT verified successfully 说明验签链路已经通了剩下就是权限规则的问题。另外提一个实用性很强的工具Postman 对 OAuth2 支持很完善可以在 Postman 里配置一个 Authorization Code 类型授权填入 clientId、clientSecret、授权端点、令牌端点、回调地址。这样每次点击 Get New Access Token 就能自动跑完整套流程不用每次手工拼 URL 或者复制 code我在调试阶段基本用它代替浏览器效率高很多。5.3 必须记住的坑CORS、静态资源与端口占用三个看起来跟 OAuth2 没关系、实际特别影响体验的点。第一个是 CORS。前后端分离时前端 SPA 从 8080 端口访问认证服务从 8081 端口访问资源服务跨域是跑不了的。认证服务只需要处理表单登录和重定向跨域配置可以简单一点资源服务则要仔细配置 CORS否则前端带着 token 请求接口也会被浏览器拦截。Spring Security 里用 CorsConfigurationSource 注册允许的域名和方法即可。第二个是静态资源。如果我用了 thymeleaf 做登录页、授权确认页页面上引用的 css、js 资源路径需要确保在过滤器链中放行否则登录页面主题加载失败。虽然不影响登录逻辑但会让演示和排错体验大打折扣。给静态资源目录加 permitAll 是常用的做法。第三个是端口占用。VSCode 里同时调试两个 Spring Boot 项目时常会遇到 8080 被占用或者 8081 被占用导致项目起不来。先到 application.yml 里确认两个服务的端口没有打架再用 lsof -i:8080 这类命令查看当前占用情况别傻傻地在那里纠结代码为什么跑不通。Spring Boot 3.X 还支持 server.port0 随机端口但 OAuth2 联调场景下必须用固定端口否则 issuer-uri 和回调地址全部对不上。6. 扩展思路让认证体系更适合真实项目6.1 自定义 JWT 声明往令牌里塞业务信息前面提到资源服务可以从 JWT 中读取 subject 和 scope但真实业务往往还需要更多字段比如用户昵称、所属部门、角色列表。在 Spring Authorization Server 中可以通过自定义 OAuth2TokenCustomizer 往 JWT 里追加信息Bean public OAuth2TokenCustomizerJwtEncodingContext tokenCustomizer() { return context - { if (context.getPrincipal() instanceof UsernamePasswordAuthenticationToken) { UsernamePasswordAuthenticationToken auth (UsernamePasswordAuthenticationToken) context.getPrincipal(); context.getClaims().claim(nickname, 演示用户); context.getClaims().claim(deptId, 1001); } }; }这段代码的作用是每次签发 JWT 时往 claims 里面塞自定义字段。资源服务读取时用 jwt.getClaimAsString(nickname) 就能直接拿到。但要注意别往 JWT 里塞敏感信息比如手机号、身份证号因为 JWT 默认只是 Base64 编码载荷不是加密的任何人拿到 token 都能解出 payload 内容。落库之外的敏感数据一律别放进来。6.2 数据库存储客户端与令牌管理InMemory 的 RegisteredClientRepository 只在学习阶段好用正式项目里客户端可能是动态注册的时刻需要新增、修改、停用不落库会很难管理。Spring Authorization Server 内置了 JDBC 支持只要引入 spring-jdbc 和对应数据库驱动把官方提供的建表脚本执行一遍然后注入 JdbcRegisteredClientRepository 就能使用。同理AuthorizationService、TokenSettings 等也可以换成数据库存储实现令牌的持久化。这样就算认证服务重启之前签发的授权码和 refresh token 仍然有效不至于让所有在线用户集体掉线。这类改造在工作量上不大但对生产环境的稳定性帮助很明显。6.3 与 Gateway 网关组合成统一认证入口如果是微服务架构通常不建议每个业务服务都直接接入资源服务器逻辑而是在网关层做统一的令牌校验。Spring Cloud Gateway 配合 spring-boot-starter-oauth2-resource-server可以在网关过滤器里解析 JWT再把用户信息通过 header 转发给下游服务。这样下游服务无需关心认证细节专注业务开发。我在帮朋友梳理一个大学生就业推荐系统的认证方案时就是采用这种结构认证服务独立部署网关层校验 token推荐的算法服务、岗位服务、简历服务全部以内网服务的方式接收网关转发的用户信息彼此之间不再各自验签。这种方案的优点在于认证逻辑收敛到一个入口后面想改 token 有效期、加白名单、做灰度都在网关处一次性完成。7. 一些掏心窝的经验整套 Spring Boot 3.X 的 OAuth2 认证与资源服务体系刚上手时确实感觉配置比旧版多了不少但真正把流程跑通之后你会意识到这些复杂度其实是协议本身要求的Spring 只是把选择权放在了你手里而已。不要一上来就追求把所有模式都学会先把授权码模式和客户端模式玩熟练再慢慢补 PKCE、OIDC、动态客户端注册认知会扎实很多。我在调试过程中反复用到一个技巧就是理解 OAuth2 的信任链模型资源服务器信任认证服务器的公钥客户端信任认证服务器的令牌端点用户信任授权页面。遇到任何权限问题沿着这条信任链从头到尾排查比翻日志死磕某一处代码要高效得多也更容易定位到具体配置错误。最后再分享一个小经验如果是在团队里做 OAuth2 相关项目强烈建议写一份内部调试手册把授权码模式的完整流程、Postman 的配置方式、常见 401 的处理清单整理成文档。因为这套机制的排错链路比较长新手入门时最容易迷失的地方恰恰是那些最简单但在文档里找不到的细节。有一份顺手的调试手册能帮整个团队省下大量在这些坑里反复试探的时间。
