spring-addons入门必读：5分钟搞懂OAuth2客户端与资源服务器的本质区别

spring-addons入门必读5分钟搞懂OAuth2客户端与资源服务器的本质区别【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addons刚接触 Spring Boot 的 OAuth2 / OpenID 安全配置时几乎每个人都会卡在同一个问题上我的应用到底该配成 OAuth2 客户端Client还是资源服务器Resource Server选错了方向后面的所有配置都会越走越偏。本文基于 spring-addons 项目一个为 Spring Boot 提供 OAuth2 / OpenID REST 自动配置的增强组件集合的官方教程与源码用 5 分钟帮你彻底搞懂二者的本质区别并给出 spring-addons 的快速落地配置参考。什么是 spring-addons为什么新手需要它spring-addons 是一组专门为 Spring Boot 应用简化 OAuth2 / OpenID 安全配置的开源自动配置组件核心模块包括spring-addons-starter-oidc在官方spring-boot-starter-oauth2-client或spring-boot-starter-oauth2-resource-server之上提供补充自动配置多数场景下能把 Java 安全配置代码降到0 行spring-addons-starter-rest为RestClient、WebClient与HttpExchange代理提供开箱即用的 OAuth2 Bearer 认证、SSL、代理等配置spring-addons-oauth2-test与spring-addons-starter-oidc-test用注解快速填充测试安全上下文在动手写代码之前先理解 OAuth2 中最基本的角色划分这会直接影响你选择哪个 starter。OAuth2 四个角色先分清谁是谁OAuth2 协议中有四个经典角色新手最容易混淆的就是其中两个角色英文一句话理解资源所有者Resource Owner最终用户拥有数据的人授权服务器Authorization Server签发和验证令牌的服务也叫 OIDC Provider如 Keycloak、Auth0客户端Client负责获取令牌并代表用户访问资源的软件资源服务器Resource Server校验令牌并返回资源的 API通常是 REST 接口其中OAuth2 客户端与资源服务器的区别是整个安全架构的分水岭也是最容易踩坑的地方。OAuth2客户端与资源服务器的 5 个本质区别很多新手误以为资源服务器 能访问资源的服务其实恰恰相反。两者的职责和配置要求几乎是相反的我用一张对比表帮你快速建立认知维度OAuth2 客户端 (Client)资源服务器 (Resource Server)核心职责从授权服务器获取令牌并给请求添加 Bearer 头校验令牌有效性issuer、audience、过期时间再做访问控制会话浏览器场景下通常需要 Session Cookie通常无状态Stateless状态都在令牌里登录/登出由它发起登录、登出流程授权码模式完全不关心登录登出只认令牌请求方式自己主动设置Authorization: Bearer xxx被动接收并校验Authorization: Bearer xxxCSRF 防护基于 Cookie 会话必须开启 CSRF 防护无状态通常关闭 CSRF简单记忆客户端是求令牌、带令牌的一方资源服务器是验令牌、给数据的一方。一张图看懂 OAuth2 授权码流程要真正理解上述区别最好的方式就是看一次完整的授权码流程Authorization Code Flow它是 OAuth2 客户端登录最常见的流程流程核心步骤客户端获取授权服务器 OpenID 配置.well-known/openid-configuration用户浏览器被重定向到授权服务器登录并返回授权码 code客户端用 code 向令牌端点换取Access Token客户端携带Authorization: Bearer token请求资源服务器资源服务器验证令牌JWT 解码或 introspection返回数据注意看登录、换令牌是客户端的事验令牌才是资源服务器的事。二者职责边界清晰Spring 才会提供两个不同的 starter。如何判断你的应用该配成哪一种(最实用的判断方法)这是新手问得最多的问题判断标准其实很简单你的应用是REST API接收别人传来的令牌→ 配资源服务器你的应用服务于浏览器 UIThymeleaf 页面或作为 BFF→ 配客户端两种都有→ 可以同时配稍后我会介绍官方方案这里有个重要提醒前端页面本身不一定是 OAuth2 客户端。在 BFFBackend For Frontend模式下OAuth2 客户端位于服务端浏览器只持有 Session Cookie完全接触不到令牌。资源服务器配置要点无状态 REST API 的安全实践如果你确定应用是资源服务器配置上应该遵循这几条资源服务器安全配置要点使用spring-boot-starter-oauth2-resource-server依赖会话管理设为STATELESS无状态禁用 CSRF因为没有 Cookie 会话未授权请求返回401而不是重定向到登录页配置 CORS允许匿名预检请求项目中完整的可运行示例位于samples/tutorials/servlet-resource-server/Servlet 版与samples/tutorials/reactive-resource-server/WebFlux 版其WebSecurityConfig.java展示了用官方 starter 手写安全过滤链的完整写法。而使用spring-addons-starter-oidc时多数资源服务器配置可以直接用 application 属性完成Java 配置代码几乎归零还支持同时信任多个异构的授权服务器Keycloak、Auth0、Cognito 并存。OAuth2客户端配置要点登录登出与会话安全如果应用是服务浏览器 UI 的 OAuth2 客户端配置重点则完全不同使用spring-boot-starter-oauth2-client依赖开启oauth2Login授权码登录必须有 Session因此必须开启 CSRF 防护配置 RP-Initiated Logout登出授权服务器会话未登录访问受保护页面时返回302 重定向到登录页可运行示例见samples/tutorials/servlet-client/与samples/tutorials/reactive-client/。在 Keycloak 管理后台注册客户端时需要将 Access Type 设置为confidential机密客户端这样才能安全保存 client-secret一个应用能同时当客户端和资源服务器吗可以实际项目中经常遇到同一个应用既要开放 REST API资源服务器又要提供 Thymeleaf 页面客户端的需求。spring-addons 官方教程samples/tutorials/resource-server_with_ui/给出了标准解法定义两条有序的 SecurityFilterChain。第一条客户端配置登录、登出用securityMatcher限定只处理 UI 资源第二条资源服务器配置无 matcher、优先级更低兜底处理其余 REST 请求界面上的效果大致是这样的——同一个后端既处理页面登录也处理 Bearer 令牌请求注意页面与 API 用不同的安全机制保护Session Cookie vs JWT页面内部的Controller通过RestClient/WebClient携带会话中的令牌去调用自己的 API——这正是spring-addons-starter-rest大显身手的地方。新手最常见的 3 个 OAuth2 误区误区一scope 就是角色权限。错。scope 是用户允许客户端替他做什么的委托范围不是角色。角色的映射需要你根据授权服务器的私有 claim如 Keycloak 的realm_access.roles自定义转换器。误区二资源服务器也要配登录页。错。资源服务器不关心登录只认令牌有效性。配了登录页反而破坏了无状态设计。误区三前端就是 OAuth2 客户端。不一定。SPA 如今更推荐走 BFF 模式由服务端客户端持有令牌浏览器只见 Session。总结5 分钟记住这张心智图最后帮你把全文浓缩成一句话客户端负责要令牌、带令牌资源服务器负责验令牌、给数据前者要会话、要登录登出、开 CSRF后者无状态、只验 Bearer 令牌、关 CSRF。搞清这个OAuth2客户端与资源服务器的本质区别后再去读 spring-addons 的教程和源码核心自动配置在spring-addons-starter-oidc/src/main/java/目录下你会发现所有配置都豁然开朗。想快速上手直接 clone 仓库https://gitcode.com/gh_mirrors/sp/spring-addons运行samples/tutorials/下的任一教程对照本文再实践一遍效果最佳。【免费下载链接】spring-addonsAdditional Spring Boot auto-configuration for OAuth2 / OpenID REST项目地址: https://gitcode.com/gh_mirrors/sp/spring-addons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考