2026/8/8 2:35:03
FEATURED · 精选文章 
1. 从单体到微服务为什么权限管理需要OAuth2如果你做过几个Spring Boot项目尤其是在尝试将单体应用拆分成微服务之后一定会遇到一个头疼的问题用户登录状态和权限怎么在服务之间共享在单体应用里一个HttpSession或者一个ThreadLocal就能搞定用户登录后权限信息存在服务端内存里每次请求从Session里取出来校验一下就行。但到了微服务架构下用户请求可能先打到网关再路由到A服务A服务内部又调用了B服务。你不可能让用户在每个服务上都登录一遍更不可能把Session复制到所有服务节点。这时候OAuth2就登场了。很多人一听到OAuth2第一反应是“第三方登录”比如“用微信扫码登录我们的网站”。这确实是OAuth2最广为人知的场景授权码模式但它的本质是一套授权框架核心是解决“在不需要暴露用户密码的情况下让一个应用能够访问用户在另一个应用中的受保护资源”。把这个思想用到我们自己的微服务系统内部就变成了让一个服务资源服务能够信任并识别来自另一个服务认证服务颁发的“令牌”从而判断当前请求者是谁、有什么权限。Spring Security 5.x 对OAuth2的支持已经非常成熟和模块化它把OAuth2的客户端Client、资源服务器Resource Server和授权服务器Authorization Server角色清晰地分离了出来。这意味着你可以轻松地搭建一个独立的认证中心授权服务器然后让其他所有业务服务资源服务器都信任这个中心颁发的令牌。用户只需要登录一次拿到一个叫access_token的令牌之后访问任何服务的API时只要在请求头里带上这个令牌Authorization: Bearer各个服务自己就能验证令牌的有效性并提取出用户身份信息完全不需要再找认证中心确认除非要检查令牌是否被吊销。所以整合Spring Security和OAuth2不是为了赶时髦而是为了解决分布式系统下的统一认证与授权这个实实在在的工程问题。接下来我会以一个典型的“认证中心 资源服务”的微服务场景为例带你一步步实现并重点剖析那些官方文档可能一笔带过但实际开发中一定会踩到的坑。2. 核心概念与架构选型JWT还是Opaque Token在动手写代码之前我们必须先搞清楚两个关键概念授权服务器和资源服务器以及一个至关重要的选择——令牌格式。授权服务器Authorization Server这是系统的安全大脑。它的职责包括管理用户认证登录。管理客户端比如Web前端、移动App的注册信息client_id, client_secret。颁发访问令牌access_token和刷新令牌refresh_token。可选提供令牌的校验接口/oauth/check_token和用户信息接口/userinfo。在Spring Security OAuth2中我们通常使用EnableAuthorizationServer注解来标记一个服务为授权服务器。不过需要注意的是在Spring Security 5.2之后这个注解已被标记为Deprecated官方推荐使用更符合OAuth 2.1规范的独立实现如Spring Authorization Server。但对于大量现存项目和Spring Security 5.x的用户基于spring-security-oauth2-autoconfigure的这套方案依然稳定且资料丰富我们本文仍以此为例进行整合。资源服务器Resource Server这就是我们的各个业务微服务。它们的职责是提供受保护的API资源比如/api/orders,/api/users。验证请求携带的access_token是否有效、是否过期、权限是否足够。从有效的令牌中提取用户身份如用户名、角色用于业务逻辑。我们使用EnableResourceServer注解来标记一个服务为资源服务器。现在来看令牌格式这是决定系统性能和架构的关键。Opaque Token不透明令牌就是一个随机字符串本身不携带任何信息。资源服务器收到这个令牌后必须调用授权服务器提供的/oauth/check_token端点去验证令牌的有效性并获取对应的用户信息。这种方式的优点是令牌本身不可被解析安全性高服务端可以随时吊销令牌。缺点是每次API调用都伴随一次网络请求增加了延迟和授权服务器的压力也使得资源服务器必须时刻与授权服务器保持连通。JWTJSON Web Token是一种开放标准RFC 7519令牌本身是一个经过数字签名或加密的JSON字符串。它由三部分组成Header.Payload.Signature其中Payload部分就包含了用户身份sub、过期时间exp、权限scope等信息。资源服务器只需要用授权服务器公布的公钥对于RS256等非对称签名算法或共享的密钥对于HS256对称签名算法来验证JWT的签名就能确认令牌的合法性和有效性无需再请求授权服务器。为什么JWT更适合微服务微服务架构强调去中心化和高可用。如果使用Opaque Token认证中心就成了一个必须时刻可用的单点。一旦认证中心宕机所有资源服务都无法验证令牌整个系统就瘫痪了。而JWT使得资源服务可以离线验证实现了认证的“去中心化”系统的鲁棒性更强。同时避免了每次请求的远程校验性能也更好。因此在现代微服务架构中JWT几乎是标配。我们接下来的整合也将基于JWT令牌进行。你需要理解的是授权服务器负责用私钥“签发”JWT而资源服务器用对应的公钥“验签”。3. 搭建授权服务器不仅仅是配置我们首先创建一个独立的Spring Boot项目作为授权服务器。除了基础的Web依赖需要引入以下关键依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdorg.springframework.security.oauth.boot/groupId artifactIdspring-security-oauth2-autoconfigure/artifactId version2.6.8/version !-- 请匹配你的Spring Boot版本 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId !-- 可选用于存储token和client信息到数据库 -- /dependency dependency groupIdcom.auth0/groupId artifactIdjava-jwt/artifactId version4.4.0/version !-- 用于生成和解析JWT -- /dependency3.1 核心配置类AuthorizationServerConfigurerAdapter创建一个配置类继承AuthorizationServerConfigurerAdapter这是配置授权服务器的核心。Configuration EnableAuthorizationServer public class AuthorizationServerConfig extends AuthorizationServerConfigurerAdapter { Autowired private AuthenticationManager authenticationManager; // 用于密码模式 Autowired private DataSource dataSource; // 用于存储客户端信息和令牌 Autowired private UserDetailsService userDetailsService; // 用于加载用户信息 Autowired private JwtAccessTokenConverter jwtAccessTokenConverter; // JWT转换器 /** * 配置客户端详情服务ClientDetailsService * 客户端信息可以存在内存中也可以像这里一样存入数据库便于管理。 */ Override public void configure(ClientDetailsServiceConfigurer clients) throws Exception { // 使用JdbcClientDetailsService从数据库读取客户端配置 clients.jdbc(dataSource); // 内存配置示例不推荐生产环境使用 // clients.inMemory() // .withClient(web-app) // client_id // .secret(passwordEncoder().encode(secret)) // client_secret必须加密 // .authorizedGrantTypes(authorization_code, password, refresh_token) // 支持的授权模式 // .scopes(read, write) // 权限范围 // .redirectUris(http://localhost:8080/login/oauth2/code/web-app) // 回调地址 // .accessTokenValiditySeconds(3600) // access_token有效期1小时 // .refreshTokenValiditySeconds(86400); // refresh_token有效期1天 } /** * 配置授权、令牌端点及其安全约束 */ Override public void configure(AuthorizationServerEndpointsConfigurer endpoints) { endpoints.authenticationManager(authenticationManager) // 密码模式必需 .userDetailsService(userDetailsService) // 刷新令牌时获取用户信息 .accessTokenConverter(jwtAccessTokenConverter) // 使用JWT令牌 .reuseRefreshTokens(false); // 刷新令牌后旧的refresh_token是否重用 } /** * 配置授权端点的安全约束比如 /oauth/authorize, /oauth/token */ Override public void configure(AuthorizationServerSecurityConfigurer security) { security.tokenKeyAccess(permitAll()) // 公开 /oauth/token_key 端点用于获取JWT签名公钥 .checkTokenAccess(isAuthenticated()) // 校验令牌端点 /oauth/check_token 需要认证 .allowFormAuthenticationForClients(); // 允许客户端使用表单认证client_id, client_secret放在参数里 } }这里有几个关键点客户端存储生产环境强烈建议使用JdbcClientDetailsService将客户端信息client_id, secret, 授权类型等存入数据库对应表oauth_client_details方便动态管理。内存配置只适用于demo。JWT转换器JwtAccessTokenConverter是将默认的Opaque Token转换为JWT的关键组件。我们需要将其配置为Bean。端点安全tokenKeyAccess(permitAll())非常重要它让资源服务器能公开访问到用于验证JWT签名的公钥。3.2 生成与配置JWT签名密钥JWT的安全性依赖于签名。我们使用非对称加密RSA授权服务器用私钥签名资源服务器用公钥验证。Configuration public class JwtConfig { Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter(); // 方式一使用对称密钥HS256 - 简单但不推荐微服务因为所有服务都知道密钥 // converter.setSigningKey(my-secret-key-12345); // 方式二使用非对称密钥对RS256 - 推荐 KeyStoreKeyFactory keyStoreKeyFactory new KeyStoreKeyFactory( new ClassPathResource(jwt.jks), // JKS密钥库文件放在resources目录下 keystore-pass.toCharArray() // 密钥库密码 ); converter.setKeyPair(keyStoreKeyFactory.getKeyPair(jwt-key)); // 密钥别名 return converter; } // 资源服务器需要这个Bean来获取公钥 Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } }如何生成jwt.jks文件你可以使用Java的keytool命令keytool -genkeypair -alias jwt-key -keyalg RSA -keypass key-pass -keystore jwt.jks -storepass keystore-pass -validity 365 -keysize 2048将生成的jwt.jks文件放到授权服务器项目的src/main/resources/目录下。key-pass是密钥条目的密码keystore-pass是密钥库的密码在代码中配置时需要对应上。3.3 配置用户详情服务与密码编码器授权服务器需要知道用户是否存在、密码是否正确。我们配置一个简单的内存用户生产环境需连接数据库。Configuration EnableWebSecurity public class WebSecurityConfig extends WebSecurityConfigurerAdapter { Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } Bean Override public AuthenticationManager authenticationManagerBean() throws Exception { return super.authenticationManagerBean(); } Override protected void configure(AuthenticationManagerBuilder auth) throws Exception { // 在内存中配置一个用户实际项目应从数据库加载 auth.inMemoryAuthentication() .withUser(user) .password(passwordEncoder().encode(password)) .roles(USER); } Bean Override public UserDetailsService userDetailsServiceBean() throws Exception { return super.userDetailsServiceBean(); } }至此一个基本的、支持密码模式和刷新令牌模式、并颁发JWT的授权服务器就搭建好了。启动后你可以通过POST /oauth/token端点来获取令牌。获取令牌测试使用密码模式curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2ViLWFwcDpzZWNyZXQ \ # Basic Auth值是 client_id:client_secret 的Base64编码 -H Content-Type: application/x-www-form-urlencoded \ -d grant_typepasswordusernameuserpasswordpassword如果成功你会收到一个包含access_tokenJWT格式和refresh_token的JSON响应。4. 搭建资源服务器验证与提取用户信息现在我们创建另一个Spring Boot项目作为资源服务器。它需要能验证JWT并保护自己的API。依赖方面只需要spring-security-oauth2-autoconfigure和spring-boot-starter-web。4.1 资源服务器配置配置类比授权服务器简单很多核心是告诉资源服务器如何验证JWT。Configuration EnableResourceServer // 关键注解声明本服务为资源服务器 public class ResourceServerConfig extends ResourceServerConfigurerAdapter { Autowired private TokenStore tokenStore; // 用于解析JWT /** * 配置资源服务器的安全规则哪些路径需要什么权限 */ Override public void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers(/api/public/**).permitAll() // 公开接口 .antMatchers(/api/admin/**).hasRole(ADMIN) // 需要ADMIN角色 .antMatchers(/api/**).authenticated() // 其他/api开头的接口需要认证 .anyRequest().permitAll(); // 其他请求如健康检查放行 } /** * 配置资源服务器的其他属性主要是令牌服务 */ Override public void configure(ResourceServerSecurityConfigurer resources) { resources.tokenStore(tokenStore) // 指定令牌存储方式为JWT .resourceId(order-service); // 资源ID可选用于匹配授权服务器颁发的令牌的audience } }4.2 配置JWT令牌解析资源服务器需要知道授权服务器的公钥来验证JWT签名。我们同样配置一个TokenStoreBean但这里只需要公钥。Configuration public class JwtResourceServerConfig { // 从授权服务器暴露的公钥端点获取公钥 Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter(); // 关键设置验证JWT签名用的公钥。 // 方式一推荐从授权服务器的/oauth/token_key端点远程获取需授权服务器配置tokenKeyAccess(permitAll()) // converter.setVerifierKey(getPublicKeyFromAuthServer()); // 方式二直接配置公钥字符串如果授权服务器使用对称密钥则用setSigningKey // 我们从之前生成的jks文件中提取公钥并配置在这里。 String publicKey -----BEGIN PUBLIC KEY-----\n MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1...你的公钥内容...\n -----END PUBLIC KEY-----; converter.setVerifierKey(publicKey); return converter; } // 一个从授权服务器动态获取公钥的示例方法 private String getPublicKeyFromAuthServer() { // 使用RestTemplate调用 http://auth-server:8080/oauth/token_key // 解析返回的JSON中的value字段即为公钥字符串 // 注意处理缓存避免每次请求都调用 } }实操心得公钥管理在实际项目中硬编码公钥字符串不利于维护特别是当授权服务器的密钥轮转时。最佳实践是让资源服务器从授权服务器提供的/oauth/token_key端点动态获取公钥并做好本地缓存例如缓存24小时。这样授权服务器更换密钥对后只需要更新JKS文件资源服务器会在缓存过期后自动获取新的公钥实现无缝切换。4.3 在控制器中获取当前用户信息令牌验证通过后Spring Security会将JWT中的用户信息主要是user_name和authorities封装到Authentication对象中。我们可以很方便地在控制器里获取。RestController RequestMapping(/api/orders) public class OrderController { GetMapping(/me) public ResponseEntity? getMyOrders() { // 方式1通过SecurityContextHolder获取 Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); // 获取用户名 Collection? extends GrantedAuthority authorities authentication.getAuthorities(); // 获取权限 // 方式2直接在方法参数中注入Principal或Authentication // public ResponseEntity? getMyOrders(Principal principal) { ... } // public ResponseEntity? getMyOrders(AuthenticationPrincipal Jwt jwt) { ... } // 获取原始JWT对象 // 方式3注入OAuth2Authentication对象包含更多OAuth2特定信息 // public ResponseEntity? getMyOrders(OAuth2Authentication auth) { ... } return ResponseEntity.ok(Hello, username ! Your authorities: authorities); } GetMapping(/{id}) PreAuthorize(hasRole(USER)) // 使用方法级安全注解需要USER角色 public ResponseEntity? getOrderById(PathVariable Long id) { // 业务逻辑 return ResponseEntity.ok(Order id); } }启动资源服务器用之前获取的access_token访问受保护的接口curl -X GET \ http://localhost:8081/api/orders/me \ -H Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...你的JWT令牌如果一切正常你将看到返回的用户信息。至此一个最基本的Spring Security整合OAuth2JWT的微服务认证授权流程就跑通了。5. 深度踩坑与进阶优化把流程跑通只是第一步真正上线后会遇到各种问题。下面分享几个我踩过的大坑和对应的解决方案。5.1 令牌过期与刷新如何实现无感续期JWT的access_token有效期通常较短如1小时以降低令牌泄露的风险。但用户不可能每小时登录一次。这就需要refresh_token。refresh_token有效期很长如7天且只能用于获取新的access_token不能直接访问资源。标准刷新流程客户端在access_token过期后使用refresh_token调用授权服务器的/oauth/token端点grant_typerefresh_token。授权服务器验证refresh_token有效后颁发新的access_token和refresh_token可选取决于配置reuseRefreshTokens。客户端使用新的access_token继续请求。前端无感刷新策略 这是前端工程师常问的问题。核心思路是拦截401响应。在请求拦截器中如果收到401状态码判断是否是因access_token过期引起可通过错误信息或自定义逻辑判断。如果是则锁定后续所有API请求放入队列静默发起一个刷新令牌的请求使用refresh_token。刷新成功后更新本地存储的access_token和新的refresh_token然后重试之前被锁定的请求。如果刷新失败如refresh_token也过期则跳转到登录页。后端服务间调用对于服务A调用服务B的情况如果A的令牌过期A需要有自己的机制如定时任务去维护一个有效的客户端凭证令牌使用client_credentials模式或者由网关统一处理令牌的刷新和传递。5.2 权限细粒度控制超越简单的角色判断Spring Security默认将JWT中的scope或authorities声明转换为GrantedAuthority。但很多时候权限判断不仅仅是“是否有某个角色”而是“是否能访问某个用户自己的数据”。场景用户只能查询自己的订单管理员可以查询所有订单。简单的PreAuthorize(hasRole(USER))无法满足。解决方案方法级安全与自定义表达式启用方法级安全在主配置类上添加EnableGlobalMethodSecurity(prePostEnabled true)。自定义权限校验逻辑Service public class OrderSecurityService { public boolean isOwner(Long orderId, String username) { // 查询数据库判断orderId是否属于username Order order orderRepository.findById(orderId).orElseThrow(); return order.getCreatedBy().equals(username); } }在注解中使用自定义方法GetMapping(/{id}) PreAuthorize(orderSecurityService.isOwner(#id, authentication.name)) public ResponseEntity? getOrder(PathVariable Long id) { // ... }这里#id引用方法参数authentication.name获取当前登录用户名。通过这种方式实现了基于数据的动态权限控制。5.3 JWT令牌的“黑名单”与即时吊销难题JWT最大的优点自包含、无需查库也是它最大的缺点服务端无法主动让其失效。在用户修改密码、管理员封禁用户、或者令牌疑似泄露时我们希望立即让某个令牌作废但资源服务器只认签名它无法知道这个“有效”的令牌是否已被列入黑名单。常见解决方案对比缩短令牌有效期 使用刷新令牌这是最基本的方法将安全风险窗口期缩短。但无法应对紧急吊销。维护一个令牌黑名单Blacklist思路授权服务器维护一个已吊销但未过期的令牌IDJTI列表。资源服务器在验证JWT签名后需要额外调用一个共享的缓存如Redis查询该JTI是否在黑名单中。实现在生成JWT时为其设置一个唯一的JTI。吊销时将该JTI存入Redis并设置过期时间等于该JWT本身的剩余有效期。资源服务器通过一个Filter或自定义的TokenStore来增加黑名单检查逻辑。优缺点实现了准实时的吊销但引入了状态查询部分牺牲了JWT无状态的优势增加了网络开销。需要确保缓存的高可用。使用Opaque Token彻底回到有状态令牌每次请求都去授权服务器校验。牺牲性能换取最强的控制力。短期令牌 权限变更监听对于因权限变更如角色被撤销导致的吊销可以通过事件广播如Spring Cloud Bus RabbitMQ通知所有资源服务器让它们清空本地缓存如用户权限缓存。但这无法处理单个令牌的泄露。我的选择对于大多数内部微服务系统我采用“JWT短有效期 黑名单用于处理紧急吊销”的折中方案。将黑名单查询做成一个可选的、快速失败的组件。在非紧急情况下依赖短有效期在紧急情况下启用黑名单检查。同时确保刷新令牌的流程足够安全绑定设备、IP等。5.4 在WebFlux响应式编程环境下的整合如果你的项目使用的是Spring WebFlux如标题热词中提到的yudao-cloud项目可能涉及整合方式与传统的Servlet栈有所不同。Spring Security for WebFlux提供了一套响应式风格的API。关键区别依赖使用spring-boot-starter-webflux和spring-security-oauth2-resource-server对于资源服务器。在Spring Security 5.2中OAuth2资源服务器的支持已整合进核心模块不再需要旧的spring-security-oauth2。配置类不再继承WebSecurityConfigurerAdapter或ResourceServerConfigurerAdapter而是通过EnableWebFluxSecurity和返回SecurityWebFilterChainBean的方式进行配置。JWT解析配置一个ReactiveJwtDecoderBean来解析JWT。获取用户信息在控制器中可以注入ReactiveSecurityContextHolder或直接使用AuthenticationPrincipal注解获取Jwt对象。示例WebFlux资源服务器配置EnableWebFluxSecurity public class SecurityConfig { Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http .authorizeExchange(exchanges - exchanges .pathMatchers(/api/public/**).permitAll() .anyExchange().authenticated() ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.jwtDecoder(jwtDecoder())) ); return http.build(); } Bean public ReactiveJwtDecoder jwtDecoder() { // 从授权服务器获取JWK Set URI或直接配置公钥 return NimbusReactiveJwtDecoder.withJwkSetUri(http://auth-server:8080/.well-known/jwks.json).build(); } }响应式栈的整合更现代但需要注意依赖版本和配置方式的差异避免将Servlet栈的配置类混用。6. 生产环境部署的关键考量当你的整合代码准备上线时以下这些点必须仔细检查密钥安全管理JKS文件或密钥字符串绝不能提交到代码仓库。应通过环境变量、配置中心或云服务商的密钥管理服务如AWS KMS, Azure Key Vault来注入。在Kubernetes中可以使用Secret对象。授权服务器高可用授权服务器是系统的关键单点。即使使用JWT客户端获取令牌、刷新令牌仍然依赖它。必须部署多个实例并通过负载均衡器暴露同时确保客户端配置数据库、缓存是共享的。资源服务器的公钥缓存与轮转资源服务器从授权服务器获取公钥时一定要实现缓存如缓存24小时。并处理好授权服务器密钥轮转时的过渡期建议新老密钥并行一段时间。令牌端点防护/oauth/token端点暴露在外是攻击重点。必须启用HTTPS并考虑增加额外的防护措施如对客户端IP进行限流、使用更复杂的客户端认证方式如TLS客户端证书。监控与审计详细记录授权服务器的令牌颁发、刷新、吊销日志。监控令牌的使用频率和模式及时发现异常如某个令牌在极短时间内从全球多个IP地址使用。定义清晰的Scope范围不要滥用Scope。Scope代表的是“访问权限的范围”比如read:orders,write:users。它应该比角色Role更细粒度用于在客户端层面进行授权。服务内部的权限判断应主要基于从JWT中提取出的用户角色和自定义逻辑。整合Spring Security与OAuth2是一个系统工程从跑通Demo到稳定服务于生产中间有大量的细节需要打磨。理解其核心原理授权码、密码、客户端等模式JWT vs Opaque Token明确架构选择资源/授权服务器分离并妥善处理令牌生命周期、权限细粒度控制、安全吊销等难题才能构建出一个既安全又高效的分布式系统认证授权体系。
Spring Security整合OAuth2与JWT：构建微服务统一认证授权体系
1. 从单体到微服务为什么权限管理需要OAuth2如果你做过几个Spring Boot项目尤其是在尝试将单体应用拆分成微服务之后一定会遇到一个头疼的问题用户登录状态和权限怎么在服务之间共享在单体应用里一个HttpSession或者一个ThreadLocal就能搞定用户登录后权限信息存在服务端内存里每次请求从Session里取出来校验一下就行。但到了微服务架构下用户请求可能先打到网关再路由到A服务A服务内部又调用了B服务。你不可能让用户在每个服务上都登录一遍更不可能把Session复制到所有服务节点。这时候OAuth2就登场了。很多人一听到OAuth2第一反应是“第三方登录”比如“用微信扫码登录我们的网站”。这确实是OAuth2最广为人知的场景授权码模式但它的本质是一套授权框架核心是解决“在不需要暴露用户密码的情况下让一个应用能够访问用户在另一个应用中的受保护资源”。把这个思想用到我们自己的微服务系统内部就变成了让一个服务资源服务能够信任并识别来自另一个服务认证服务颁发的“令牌”从而判断当前请求者是谁、有什么权限。Spring Security 5.x 对OAuth2的支持已经非常成熟和模块化它把OAuth2的客户端Client、资源服务器Resource Server和授权服务器Authorization Server角色清晰地分离了出来。这意味着你可以轻松地搭建一个独立的认证中心授权服务器然后让其他所有业务服务资源服务器都信任这个中心颁发的令牌。用户只需要登录一次拿到一个叫access_token的令牌之后访问任何服务的API时只要在请求头里带上这个令牌Authorization: Bearer各个服务自己就能验证令牌的有效性并提取出用户身份信息完全不需要再找认证中心确认除非要检查令牌是否被吊销。所以整合Spring Security和OAuth2不是为了赶时髦而是为了解决分布式系统下的统一认证与授权这个实实在在的工程问题。接下来我会以一个典型的“认证中心 资源服务”的微服务场景为例带你一步步实现并重点剖析那些官方文档可能一笔带过但实际开发中一定会踩到的坑。2. 核心概念与架构选型JWT还是Opaque Token在动手写代码之前我们必须先搞清楚两个关键概念授权服务器和资源服务器以及一个至关重要的选择——令牌格式。授权服务器Authorization Server这是系统的安全大脑。它的职责包括管理用户认证登录。管理客户端比如Web前端、移动App的注册信息client_id, client_secret。颁发访问令牌access_token和刷新令牌refresh_token。可选提供令牌的校验接口/oauth/check_token和用户信息接口/userinfo。在Spring Security OAuth2中我们通常使用EnableAuthorizationServer注解来标记一个服务为授权服务器。不过需要注意的是在Spring Security 5.2之后这个注解已被标记为Deprecated官方推荐使用更符合OAuth 2.1规范的独立实现如Spring Authorization Server。但对于大量现存项目和Spring Security 5.x的用户基于spring-security-oauth2-autoconfigure的这套方案依然稳定且资料丰富我们本文仍以此为例进行整合。资源服务器Resource Server这就是我们的各个业务微服务。它们的职责是提供受保护的API资源比如/api/orders,/api/users。验证请求携带的access_token是否有效、是否过期、权限是否足够。从有效的令牌中提取用户身份如用户名、角色用于业务逻辑。我们使用EnableResourceServer注解来标记一个服务为资源服务器。现在来看令牌格式这是决定系统性能和架构的关键。Opaque Token不透明令牌就是一个随机字符串本身不携带任何信息。资源服务器收到这个令牌后必须调用授权服务器提供的/oauth/check_token端点去验证令牌的有效性并获取对应的用户信息。这种方式的优点是令牌本身不可被解析安全性高服务端可以随时吊销令牌。缺点是每次API调用都伴随一次网络请求增加了延迟和授权服务器的压力也使得资源服务器必须时刻与授权服务器保持连通。JWTJSON Web Token是一种开放标准RFC 7519令牌本身是一个经过数字签名或加密的JSON字符串。它由三部分组成Header.Payload.Signature其中Payload部分就包含了用户身份sub、过期时间exp、权限scope等信息。资源服务器只需要用授权服务器公布的公钥对于RS256等非对称签名算法或共享的密钥对于HS256对称签名算法来验证JWT的签名就能确认令牌的合法性和有效性无需再请求授权服务器。为什么JWT更适合微服务微服务架构强调去中心化和高可用。如果使用Opaque Token认证中心就成了一个必须时刻可用的单点。一旦认证中心宕机所有资源服务都无法验证令牌整个系统就瘫痪了。而JWT使得资源服务可以离线验证实现了认证的“去中心化”系统的鲁棒性更强。同时避免了每次请求的远程校验性能也更好。因此在现代微服务架构中JWT几乎是标配。我们接下来的整合也将基于JWT令牌进行。你需要理解的是授权服务器负责用私钥“签发”JWT而资源服务器用对应的公钥“验签”。3. 搭建授权服务器不仅仅是配置我们首先创建一个独立的Spring Boot项目作为授权服务器。除了基础的Web依赖需要引入以下关键依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdorg.springframework.security.oauth.boot/groupId artifactIdspring-security-oauth2-autoconfigure/artifactId version2.6.8/version !-- 请匹配你的Spring Boot版本 -- /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId !-- 可选用于存储token和client信息到数据库 -- /dependency dependency groupIdcom.auth0/groupId artifactIdjava-jwt/artifactId version4.4.0/version !-- 用于生成和解析JWT -- /dependency3.1 核心配置类AuthorizationServerConfigurerAdapter创建一个配置类继承AuthorizationServerConfigurerAdapter这是配置授权服务器的核心。Configuration EnableAuthorizationServer public class AuthorizationServerConfig extends AuthorizationServerConfigurerAdapter { Autowired private AuthenticationManager authenticationManager; // 用于密码模式 Autowired private DataSource dataSource; // 用于存储客户端信息和令牌 Autowired private UserDetailsService userDetailsService; // 用于加载用户信息 Autowired private JwtAccessTokenConverter jwtAccessTokenConverter; // JWT转换器 /** * 配置客户端详情服务ClientDetailsService * 客户端信息可以存在内存中也可以像这里一样存入数据库便于管理。 */ Override public void configure(ClientDetailsServiceConfigurer clients) throws Exception { // 使用JdbcClientDetailsService从数据库读取客户端配置 clients.jdbc(dataSource); // 内存配置示例不推荐生产环境使用 // clients.inMemory() // .withClient(web-app) // client_id // .secret(passwordEncoder().encode(secret)) // client_secret必须加密 // .authorizedGrantTypes(authorization_code, password, refresh_token) // 支持的授权模式 // .scopes(read, write) // 权限范围 // .redirectUris(http://localhost:8080/login/oauth2/code/web-app) // 回调地址 // .accessTokenValiditySeconds(3600) // access_token有效期1小时 // .refreshTokenValiditySeconds(86400); // refresh_token有效期1天 } /** * 配置授权、令牌端点及其安全约束 */ Override public void configure(AuthorizationServerEndpointsConfigurer endpoints) { endpoints.authenticationManager(authenticationManager) // 密码模式必需 .userDetailsService(userDetailsService) // 刷新令牌时获取用户信息 .accessTokenConverter(jwtAccessTokenConverter) // 使用JWT令牌 .reuseRefreshTokens(false); // 刷新令牌后旧的refresh_token是否重用 } /** * 配置授权端点的安全约束比如 /oauth/authorize, /oauth/token */ Override public void configure(AuthorizationServerSecurityConfigurer security) { security.tokenKeyAccess(permitAll()) // 公开 /oauth/token_key 端点用于获取JWT签名公钥 .checkTokenAccess(isAuthenticated()) // 校验令牌端点 /oauth/check_token 需要认证 .allowFormAuthenticationForClients(); // 允许客户端使用表单认证client_id, client_secret放在参数里 } }这里有几个关键点客户端存储生产环境强烈建议使用JdbcClientDetailsService将客户端信息client_id, secret, 授权类型等存入数据库对应表oauth_client_details方便动态管理。内存配置只适用于demo。JWT转换器JwtAccessTokenConverter是将默认的Opaque Token转换为JWT的关键组件。我们需要将其配置为Bean。端点安全tokenKeyAccess(permitAll())非常重要它让资源服务器能公开访问到用于验证JWT签名的公钥。3.2 生成与配置JWT签名密钥JWT的安全性依赖于签名。我们使用非对称加密RSA授权服务器用私钥签名资源服务器用公钥验证。Configuration public class JwtConfig { Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter(); // 方式一使用对称密钥HS256 - 简单但不推荐微服务因为所有服务都知道密钥 // converter.setSigningKey(my-secret-key-12345); // 方式二使用非对称密钥对RS256 - 推荐 KeyStoreKeyFactory keyStoreKeyFactory new KeyStoreKeyFactory( new ClassPathResource(jwt.jks), // JKS密钥库文件放在resources目录下 keystore-pass.toCharArray() // 密钥库密码 ); converter.setKeyPair(keyStoreKeyFactory.getKeyPair(jwt-key)); // 密钥别名 return converter; } // 资源服务器需要这个Bean来获取公钥 Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } }如何生成jwt.jks文件你可以使用Java的keytool命令keytool -genkeypair -alias jwt-key -keyalg RSA -keypass key-pass -keystore jwt.jks -storepass keystore-pass -validity 365 -keysize 2048将生成的jwt.jks文件放到授权服务器项目的src/main/resources/目录下。key-pass是密钥条目的密码keystore-pass是密钥库的密码在代码中配置时需要对应上。3.3 配置用户详情服务与密码编码器授权服务器需要知道用户是否存在、密码是否正确。我们配置一个简单的内存用户生产环境需连接数据库。Configuration EnableWebSecurity public class WebSecurityConfig extends WebSecurityConfigurerAdapter { Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } Bean Override public AuthenticationManager authenticationManagerBean() throws Exception { return super.authenticationManagerBean(); } Override protected void configure(AuthenticationManagerBuilder auth) throws Exception { // 在内存中配置一个用户实际项目应从数据库加载 auth.inMemoryAuthentication() .withUser(user) .password(passwordEncoder().encode(password)) .roles(USER); } Bean Override public UserDetailsService userDetailsServiceBean() throws Exception { return super.userDetailsServiceBean(); } }至此一个基本的、支持密码模式和刷新令牌模式、并颁发JWT的授权服务器就搭建好了。启动后你可以通过POST /oauth/token端点来获取令牌。获取令牌测试使用密码模式curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2ViLWFwcDpzZWNyZXQ \ # Basic Auth值是 client_id:client_secret 的Base64编码 -H Content-Type: application/x-www-form-urlencoded \ -d grant_typepasswordusernameuserpasswordpassword如果成功你会收到一个包含access_tokenJWT格式和refresh_token的JSON响应。4. 搭建资源服务器验证与提取用户信息现在我们创建另一个Spring Boot项目作为资源服务器。它需要能验证JWT并保护自己的API。依赖方面只需要spring-security-oauth2-autoconfigure和spring-boot-starter-web。4.1 资源服务器配置配置类比授权服务器简单很多核心是告诉资源服务器如何验证JWT。Configuration EnableResourceServer // 关键注解声明本服务为资源服务器 public class ResourceServerConfig extends ResourceServerConfigurerAdapter { Autowired private TokenStore tokenStore; // 用于解析JWT /** * 配置资源服务器的安全规则哪些路径需要什么权限 */ Override public void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers(/api/public/**).permitAll() // 公开接口 .antMatchers(/api/admin/**).hasRole(ADMIN) // 需要ADMIN角色 .antMatchers(/api/**).authenticated() // 其他/api开头的接口需要认证 .anyRequest().permitAll(); // 其他请求如健康检查放行 } /** * 配置资源服务器的其他属性主要是令牌服务 */ Override public void configure(ResourceServerSecurityConfigurer resources) { resources.tokenStore(tokenStore) // 指定令牌存储方式为JWT .resourceId(order-service); // 资源ID可选用于匹配授权服务器颁发的令牌的audience } }4.2 配置JWT令牌解析资源服务器需要知道授权服务器的公钥来验证JWT签名。我们同样配置一个TokenStoreBean但这里只需要公钥。Configuration public class JwtResourceServerConfig { // 从授权服务器暴露的公钥端点获取公钥 Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter(); // 关键设置验证JWT签名用的公钥。 // 方式一推荐从授权服务器的/oauth/token_key端点远程获取需授权服务器配置tokenKeyAccess(permitAll()) // converter.setVerifierKey(getPublicKeyFromAuthServer()); // 方式二直接配置公钥字符串如果授权服务器使用对称密钥则用setSigningKey // 我们从之前生成的jks文件中提取公钥并配置在这里。 String publicKey -----BEGIN PUBLIC KEY-----\n MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1...你的公钥内容...\n -----END PUBLIC KEY-----; converter.setVerifierKey(publicKey); return converter; } // 一个从授权服务器动态获取公钥的示例方法 private String getPublicKeyFromAuthServer() { // 使用RestTemplate调用 http://auth-server:8080/oauth/token_key // 解析返回的JSON中的value字段即为公钥字符串 // 注意处理缓存避免每次请求都调用 } }实操心得公钥管理在实际项目中硬编码公钥字符串不利于维护特别是当授权服务器的密钥轮转时。最佳实践是让资源服务器从授权服务器提供的/oauth/token_key端点动态获取公钥并做好本地缓存例如缓存24小时。这样授权服务器更换密钥对后只需要更新JKS文件资源服务器会在缓存过期后自动获取新的公钥实现无缝切换。4.3 在控制器中获取当前用户信息令牌验证通过后Spring Security会将JWT中的用户信息主要是user_name和authorities封装到Authentication对象中。我们可以很方便地在控制器里获取。RestController RequestMapping(/api/orders) public class OrderController { GetMapping(/me) public ResponseEntity? getMyOrders() { // 方式1通过SecurityContextHolder获取 Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); // 获取用户名 Collection? extends GrantedAuthority authorities authentication.getAuthorities(); // 获取权限 // 方式2直接在方法参数中注入Principal或Authentication // public ResponseEntity? getMyOrders(Principal principal) { ... } // public ResponseEntity? getMyOrders(AuthenticationPrincipal Jwt jwt) { ... } // 获取原始JWT对象 // 方式3注入OAuth2Authentication对象包含更多OAuth2特定信息 // public ResponseEntity? getMyOrders(OAuth2Authentication auth) { ... } return ResponseEntity.ok(Hello, username ! Your authorities: authorities); } GetMapping(/{id}) PreAuthorize(hasRole(USER)) // 使用方法级安全注解需要USER角色 public ResponseEntity? getOrderById(PathVariable Long id) { // 业务逻辑 return ResponseEntity.ok(Order id); } }启动资源服务器用之前获取的access_token访问受保护的接口curl -X GET \ http://localhost:8081/api/orders/me \ -H Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...你的JWT令牌如果一切正常你将看到返回的用户信息。至此一个最基本的Spring Security整合OAuth2JWT的微服务认证授权流程就跑通了。5. 深度踩坑与进阶优化把流程跑通只是第一步真正上线后会遇到各种问题。下面分享几个我踩过的大坑和对应的解决方案。5.1 令牌过期与刷新如何实现无感续期JWT的access_token有效期通常较短如1小时以降低令牌泄露的风险。但用户不可能每小时登录一次。这就需要refresh_token。refresh_token有效期很长如7天且只能用于获取新的access_token不能直接访问资源。标准刷新流程客户端在access_token过期后使用refresh_token调用授权服务器的/oauth/token端点grant_typerefresh_token。授权服务器验证refresh_token有效后颁发新的access_token和refresh_token可选取决于配置reuseRefreshTokens。客户端使用新的access_token继续请求。前端无感刷新策略 这是前端工程师常问的问题。核心思路是拦截401响应。在请求拦截器中如果收到401状态码判断是否是因access_token过期引起可通过错误信息或自定义逻辑判断。如果是则锁定后续所有API请求放入队列静默发起一个刷新令牌的请求使用refresh_token。刷新成功后更新本地存储的access_token和新的refresh_token然后重试之前被锁定的请求。如果刷新失败如refresh_token也过期则跳转到登录页。后端服务间调用对于服务A调用服务B的情况如果A的令牌过期A需要有自己的机制如定时任务去维护一个有效的客户端凭证令牌使用client_credentials模式或者由网关统一处理令牌的刷新和传递。5.2 权限细粒度控制超越简单的角色判断Spring Security默认将JWT中的scope或authorities声明转换为GrantedAuthority。但很多时候权限判断不仅仅是“是否有某个角色”而是“是否能访问某个用户自己的数据”。场景用户只能查询自己的订单管理员可以查询所有订单。简单的PreAuthorize(hasRole(USER))无法满足。解决方案方法级安全与自定义表达式启用方法级安全在主配置类上添加EnableGlobalMethodSecurity(prePostEnabled true)。自定义权限校验逻辑Service public class OrderSecurityService { public boolean isOwner(Long orderId, String username) { // 查询数据库判断orderId是否属于username Order order orderRepository.findById(orderId).orElseThrow(); return order.getCreatedBy().equals(username); } }在注解中使用自定义方法GetMapping(/{id}) PreAuthorize(orderSecurityService.isOwner(#id, authentication.name)) public ResponseEntity? getOrder(PathVariable Long id) { // ... }这里#id引用方法参数authentication.name获取当前登录用户名。通过这种方式实现了基于数据的动态权限控制。5.3 JWT令牌的“黑名单”与即时吊销难题JWT最大的优点自包含、无需查库也是它最大的缺点服务端无法主动让其失效。在用户修改密码、管理员封禁用户、或者令牌疑似泄露时我们希望立即让某个令牌作废但资源服务器只认签名它无法知道这个“有效”的令牌是否已被列入黑名单。常见解决方案对比缩短令牌有效期 使用刷新令牌这是最基本的方法将安全风险窗口期缩短。但无法应对紧急吊销。维护一个令牌黑名单Blacklist思路授权服务器维护一个已吊销但未过期的令牌IDJTI列表。资源服务器在验证JWT签名后需要额外调用一个共享的缓存如Redis查询该JTI是否在黑名单中。实现在生成JWT时为其设置一个唯一的JTI。吊销时将该JTI存入Redis并设置过期时间等于该JWT本身的剩余有效期。资源服务器通过一个Filter或自定义的TokenStore来增加黑名单检查逻辑。优缺点实现了准实时的吊销但引入了状态查询部分牺牲了JWT无状态的优势增加了网络开销。需要确保缓存的高可用。使用Opaque Token彻底回到有状态令牌每次请求都去授权服务器校验。牺牲性能换取最强的控制力。短期令牌 权限变更监听对于因权限变更如角色被撤销导致的吊销可以通过事件广播如Spring Cloud Bus RabbitMQ通知所有资源服务器让它们清空本地缓存如用户权限缓存。但这无法处理单个令牌的泄露。我的选择对于大多数内部微服务系统我采用“JWT短有效期 黑名单用于处理紧急吊销”的折中方案。将黑名单查询做成一个可选的、快速失败的组件。在非紧急情况下依赖短有效期在紧急情况下启用黑名单检查。同时确保刷新令牌的流程足够安全绑定设备、IP等。5.4 在WebFlux响应式编程环境下的整合如果你的项目使用的是Spring WebFlux如标题热词中提到的yudao-cloud项目可能涉及整合方式与传统的Servlet栈有所不同。Spring Security for WebFlux提供了一套响应式风格的API。关键区别依赖使用spring-boot-starter-webflux和spring-security-oauth2-resource-server对于资源服务器。在Spring Security 5.2中OAuth2资源服务器的支持已整合进核心模块不再需要旧的spring-security-oauth2。配置类不再继承WebSecurityConfigurerAdapter或ResourceServerConfigurerAdapter而是通过EnableWebFluxSecurity和返回SecurityWebFilterChainBean的方式进行配置。JWT解析配置一个ReactiveJwtDecoderBean来解析JWT。获取用户信息在控制器中可以注入ReactiveSecurityContextHolder或直接使用AuthenticationPrincipal注解获取Jwt对象。示例WebFlux资源服务器配置EnableWebFluxSecurity public class SecurityConfig { Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http .authorizeExchange(exchanges - exchanges .pathMatchers(/api/public/**).permitAll() .anyExchange().authenticated() ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.jwtDecoder(jwtDecoder())) ); return http.build(); } Bean public ReactiveJwtDecoder jwtDecoder() { // 从授权服务器获取JWK Set URI或直接配置公钥 return NimbusReactiveJwtDecoder.withJwkSetUri(http://auth-server:8080/.well-known/jwks.json).build(); } }响应式栈的整合更现代但需要注意依赖版本和配置方式的差异避免将Servlet栈的配置类混用。6. 生产环境部署的关键考量当你的整合代码准备上线时以下这些点必须仔细检查密钥安全管理JKS文件或密钥字符串绝不能提交到代码仓库。应通过环境变量、配置中心或云服务商的密钥管理服务如AWS KMS, Azure Key Vault来注入。在Kubernetes中可以使用Secret对象。授权服务器高可用授权服务器是系统的关键单点。即使使用JWT客户端获取令牌、刷新令牌仍然依赖它。必须部署多个实例并通过负载均衡器暴露同时确保客户端配置数据库、缓存是共享的。资源服务器的公钥缓存与轮转资源服务器从授权服务器获取公钥时一定要实现缓存如缓存24小时。并处理好授权服务器密钥轮转时的过渡期建议新老密钥并行一段时间。令牌端点防护/oauth/token端点暴露在外是攻击重点。必须启用HTTPS并考虑增加额外的防护措施如对客户端IP进行限流、使用更复杂的客户端认证方式如TLS客户端证书。监控与审计详细记录授权服务器的令牌颁发、刷新、吊销日志。监控令牌的使用频率和模式及时发现异常如某个令牌在极短时间内从全球多个IP地址使用。定义清晰的Scope范围不要滥用Scope。Scope代表的是“访问权限的范围”比如read:orders,write:users。它应该比角色Role更细粒度用于在客户端层面进行授权。服务内部的权限判断应主要基于从JWT中提取出的用户角色和自定义逻辑。整合Spring Security与OAuth2是一个系统工程从跑通Demo到稳定服务于生产中间有大量的细节需要打磨。理解其核心原理授权码、密码、客户端等模式JWT vs Opaque Token明确架构选择资源/授权服务器分离并妥善处理令牌生命周期、权限细粒度控制、安全吊销等难题才能构建出一个既安全又高效的分布式系统认证授权体系。 
