1. 项目概述为什么我们需要在Spring Security中整合OAuth2如果你正在构建一个需要用户登录的现代Web应用或API服务那么“登录”这件事本身就已经从一个简单的用户名密码校验演变成了一个复杂的系统工程。用户可能想用微信扫码登录你的网站开发者可能需要调用你的API来获取数据企业内部系统之间也需要安全地共享用户身份。当你的Spring Boot应用还在用着HttpSecurity配置表单登录为记住我Remember-Me和CSRF防护头疼时业界早已转向了更标准、更安全、也更灵活的解决方案——OAuth 2.0和OpenID Connect。“Spring Security整合OAuth2”这个标题听起来像是一个技术组件的拼接但它的本质是为你的应用引入一套工业级的身份认证与授权协议。Spring Security本身是一个强大的安全框架它负责“守卫大门”定义谁能进、能进到哪里。而OAuth2是一套标准协议它定义了“通行证”Token的颁发、校验和使用规则。将它们整合意味着你的应用不仅能用自己的账号体系资源所有者密码凭证模式登录更能轻松地接入微信、GitHub、Google等第三方登录授权码模式或者为移动端、前端SPA应用、微服务提供安全的API访问凭证客户端凭证模式、刷新令牌。我见过太多项目初期为了快把所有安全逻辑都写死在Controller里后期要加个第三方登录或者开放API就得伤筋动骨地重构。直接从Spring Security整合OAuth2开始看似前期配置稍多实则是为未来的扩展性买了一份保险。接下来我会以一个资源服务器提供API和授权服务器颁发Token分离的典型微服务架构为例带你从设计思路到踩坑细节完整走通整合流程。2. 架构设计与核心概念澄清在动手写代码之前我们必须把几个关键角色和流程掰扯清楚这是避免后续混乱的基础。很多人配置出错就是因为对这些概念的理解是模糊的。2.1 OAuth2的四种授权模式与适用场景OAuth2的核心是解决“在不分享用户密码的前提下让第三方应用获得有限的资源访问权限”。它定义了四种模式但在与Spring Security整合时我们最常用的是其中三种授权码模式这是最安全、最完整的流程用于有前端的Web应用。用户被重定向到授权服务器的登录页面登录并授权后授权服务器通过回调地址传回一个授权码前端再用这个码去换Token。这是第三方登录如“用GitHub登录”的标准流程。密码模式用户直接向客户端提供用户名和密码客户端用这些信息直接去授权服务器换Token。这要求你对客户端高度信任通常用于自家开发的第一方应用如自家的移动端App。由于需要传输密码安全性较低OAuth 2.1已建议弃用但在内部系统或遗留整合中仍可见。客户端凭证模式没有用户参与客户端用自己的client_id和client_secret直接获取Token。这用于服务器对服务器的通信比如微服务A要调用微服务B的某个后台作业API。简化模式Token直接通过前端回调URL的片段#后面传递跳过授权码步骤。用于纯前端SPA但因其安全性问题已被PKCE扩展的授权码模式所取代。在Spring Security OAuth2的体系中授权服务器负责实现这些模式的端点如/oauth/authorize,/oauth/token而资源服务器只负责验证Token并保护API。2.2 Spring Security OAuth2的两种实现方式与选型这里有一个历史性的关键选择。Spring官方对OAuth2的支持经历过一次重大变迁Spring Security OAuth项目这是一个独立的项目在Spring Boot 2.x时代是主流。它提供了EnableAuthorizationServer和EnableResourceServer注解来快速搭建。但是这个项目已经停止维护并将在未来版本中被移除。Spring Security 5.x 原生OAuth2支持从Spring Security 5开始OAuth2的支持被直接集成到核心框架中。它遵循更标准的规范配置方式更贴近Spring Security本身的DSL领域特定语言是当前及未来的推荐方案。我们今天的整合将完全基于Spring Security 5.x的原生支持。这意味着我们不会使用那些已废弃的注解而是通过配置SecurityFilterChainBean和一系列xxxConfigurer来构建我们的安全体系。这个选择确保了项目的长期可维护性。2.3 核心依赖引入基于Spring Boot 3.x和Spring Security 6.x其理念与5.x一脉相承你的pom.xml关键依赖如下dependencies !-- Spring Boot Web 基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring Security 核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency !-- OAuth2 资源服务器支持用于保护API -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-resource-server/artifactId /dependency !-- OAuth2 授权服务器支持用于颁发Token -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-authorization-server/artifactId /dependency !-- JWT支持推荐Token格式 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-resource-server/artifactId /dependency !-- 数据库存储用于存客户端信息、授权记录等 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies注意spring-boot-starter-oauth2-authorization-server是构建授权服务器的关键。如果你只是需要一个资源服务器比如一个只提供API的微服务那么只需要resource-server依赖即可。3. 构建授权服务器自己颁发Token授权服务器是整个OAuth2体系的核心它负责认证用户身份、征得用户同意并最终颁发访问令牌Access Token。我们将构建一个支持密码模式用于演示和客户端凭证模式的授权服务器。3.1 基础安全配置与端点暴露首先我们需要配置一个基础的SecurityFilterChain来保护授权服务器自身的端点。授权服务器的关键端点如/oauth2/authorize,/oauth2/token需要被暴露出来以供客户端访问但同时其管理界面可能需要额外保护。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; import org.springframework.security.config.Customizer; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; Configuration EnableWebSecurity public class DefaultSecurityConfig { Bean Order(1) // 设置较低的优先级确保先于授权服务器配置生效 public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authorize - authorize .requestMatchers(/actuator/health, /public/**).permitAll() // 公开端点 .anyRequest().authenticated() // 其他所有请求都需要认证 ) // 启用表单登录方便我们测试授权服务器的登录页面 .formLogin(Customizer.withDefaults()); return http.build(); } }3.2 配置授权服务器这是最关键的一步。我们将创建一个专门用于OAuth2授权服务的SecurityFilterChain并使用AuthorizationServerSettings来定制端点路径。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configurers.oauth2.server.authorization.OAuth2AuthorizationServerConfigurer; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configuration.OAuth2AuthorizationServerConfiguration; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configurers.OAuth2AuthorizationServerConfigurer; import org.springframework.security.oauth2.server.authorization.settings.AuthorizationServerSettings; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint; import org.springframework.security.web.util.matcher.RequestMatcher; Configuration public class AuthorizationServerConfig { // 授权服务器本身的端点安全配置 Bean Order(2) // 优先级高于默认配置 public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception { // 应用OAuth2授权服务器的默认配置 OAuth2AuthorizationServerConfigurer authorizationServerConfigurer new OAuth2AuthorizationServerConfigurer(); // 自定义授权服务器端点请求匹配器 RequestMatcher endpointsMatcher authorizationServerConfigurer.getEndpointsMatcher(); http .securityMatcher(endpointsMatcher) // 只对授权服务器端点应用此配置 .authorizeHttpRequests(authorize - authorize .anyRequest().authenticated() ) .csrf(csrf - csrf.ignoringRequestMatchers(endpointsMatcher)) // 对OAuth2端点禁用CSRF .apply(authorizationServerConfigurer); // 应用授权服务器配置 // 当未认证用户访问受保护的授权端点时重定向到登录页 http.exceptionHandling(exceptions - exceptions .authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint(/login)) ); return http.build(); } // 配置授权服务器设置如端点路径 Bean public AuthorizationServerSettings authorizationServerSettings() { return AuthorizationServerSettings.builder() .issuer(http://auth-server:9000) // 发行者标识用于JWT的iss声明 .authorizationEndpoint(/oauth2/authorize) // 授权端点 .tokenEndpoint(/oauth2/token) // 令牌端点 .tokenIntrospectionEndpoint(/oauth2/introspect) // 令牌内省端点 .tokenRevocationEndpoint(/oauth2/revoke) // 令牌吊销端点 .jwkSetEndpoint(/oauth2/jwks) // JWK Set端点用于JWT .oidcUserInfoEndpoint(/userinfo) // OIDC用户信息端点 .build(); } }3.3 注册客户端与配置JWT客户端Client代表想要访问资源的应用程序。我们需要将客户端信息存储起来Spring Authorization Server支持内存和JDBC两种方式。为了持久化我们使用JDBC。同时我们将使用JWTJSON Web Token作为令牌格式因为它自包含、易于验证且无需服务端存储。3.3.1 数据库表结构初始化Spring Authorization Server提供了默认的SQL schema我们可以在src/main/resources下创建schema.sql-- 来自Spring Authorization Server官方示例 CREATE TABLE oauth2_registered_client ( id varchar(100) NOT NULL, client_id varchar(100) NOT NULL, client_id_issued_at timestamp DEFAULT CURRENT_TIMESTAMP NOT NULL, client_secret varchar(200) DEFAULT NULL, client_secret_expires_at timestamp DEFAULT NULL, client_name varchar(200) NOT NULL, client_authentication_methods varchar(1000) NOT NULL, authorization_grant_types varchar(1000) NOT NULL, redirect_uris varchar(1000) DEFAULT NULL, scopes varchar(1000) NOT NULL, client_settings varchar(2000) NOT NULL, token_settings varchar(2000) NOT NULL, PRIMARY KEY (id) );3.3.2 配置客户端存储与服务我们需要一个RegisteredClientRepositoryBean来管理客户端。这里我们在配置类中初始化一个客户端并存入数据库生产环境应从配置中心或管理界面动态添加。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.oauth2.core.AuthorizationGrantType; import org.springframework.security.oauth2.core.ClientAuthenticationMethod; import org.springframework.security.oauth2.core.oidc.OidcScopes; import org.springframework.security.oauth2.server.authorization.client.JdbcRegisteredClientRepository; import org.springframework.security.oauth2.server.authorization.client.RegisteredClient; import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository; import org.springframework.security.oauth2.server.authorization.settings.ClientSettings; import org.springframework.security.oauth2.server.authorization.settings.TokenSettings; import javax.sql.DataSource; import java.time.Duration; import java.util.UUID; Configuration public class ClientConfig { Bean public RegisteredClientRepository registeredClientRepository(DataSource dataSource) { // 使用JDBC存储 JdbcRegisteredClientRepository repository new JdbcRegisteredClientRepository(dataSource); // 检查并初始化一个示例客户端仅用于演示生产环境不应硬编码 if (repository.findByClientId(test-client) null) { RegisteredClient registeredClient RegisteredClient.withId(UUID.randomUUID().toString()) .clientId(test-client) .clientSecret({bcrypt}$2a$10$NlqVU3h0mM.4AqV8pQwBZeZz7J5Kc1Xq5Ld7r2f5t0g1vH2s3j4k5l6) // 明文是 secret .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC) .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) .authorizationGrantType(AuthorizationGrantType.PASSWORD) // 启用密码模式谨慎使用 .redirectUri(http://127.0.0.1:8080/login/oauth2/code/test-client) .scope(OidcScopes.OPENID) .scope(OidcScopes.PROFILE) .scope(read) .scope(write) .clientSettings(ClientSettings.builder().requireAuthorizationConsent(false).build()) // 跳过授权确认页 .tokenSettings(TokenSettings.builder() .accessTokenTimeToLive(Duration.ofHours(1)) // Access Token 1小时过期 .refreshTokenTimeToLive(Duration.ofDays(7)) // Refresh Token 7天过期 .reuseRefreshTokens(false) // 不重用Refresh Token .build()) .build(); repository.save(registeredClient); } return repository; } }3.3.3 配置JWT生成器为了让授权服务器能签发JWT格式的Token我们需要配置一个JWKSource。import com.nimbusds.jose.jwk.JWKSet; import com.nimbusds.jose.jwk.RSAKey; import com.nimbusds.jose.jwk.source.JWKSource; import com.nimbusds.jose.proc.SecurityContext; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.oauth2.jwt.JwtDecoder; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configuration.OAuth2AuthorizationServerConfiguration; import java.security.KeyPair; import java.security.KeyPairGenerator; import java.security.NoSuchAlgorithmException; import java.security.interfaces.RSAPrivateKey; import java.security.interfaces.RSAPublicKey; import java.util.UUID; Configuration public class JwtConfig { Bean public JWKSourceSecurityContext jwkSource() throws NoSuchAlgorithmException { // 生成RSA密钥对。生产环境应从安全的密钥管理服务获取并妥善保管私钥。 KeyPairGenerator keyPairGenerator KeyPairGenerator.getInstance(RSA); keyPairGenerator.initialize(2048); KeyPair keyPair keyPairGenerator.generateKeyPair(); RSAPublicKey publicKey (RSAPublicKey) keyPair.getPublic(); RSAPrivateKey privateKey (RSAPrivateKey) keyPair.getPrivate(); // 构建RSA Key RSAKey rsaKey new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(UUID.randomUUID().toString()) .build(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); } // 授权服务器需要JWT解码器来解码自己签发的Token例如在令牌内省时 Bean public JwtDecoder jwtDecoder(JWKSourceSecurityContext jwkSource) { return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); } }至此一个基本的授权服务器就配置完成了。它现在可以提供以下主要端点GET /oauth2/authorize授权端点用于授权码模式。POST /oauth2/token令牌端点用于获取所有类型的Token。POST /oauth2/introspect令牌内省端点验证Token有效性。POST /oauth2/revoke令牌吊销端点。GET /oauth2/jwks提供公钥集供资源服务器验证JWT签名。4. 构建资源服务器验证并保护API资源服务器是实际提供受保护API的服务。它不负责颁发Token只负责验证请求中携带的Token是否有效、是否具有访问特定资源的权限Scope。4.1 基础资源服务器配置资源服务器的配置相对简单核心是告诉它如何验证Token这里使用JWT并通过授权服务器发布的JWK Set端点验证签名。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.oauth2.jwt.JwtDecoder; import org.springframework.security.oauth2.jwt.NimbusJwtDecoder; import org.springframework.security.web.SecurityFilterChain; Configuration EnableWebSecurity public class ResourceServerConfig { Bean public SecurityFilterChain resourceServerFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/api/**) // 只对/api/**路径应用此配置 .authorizeHttpRequests(authorize - authorize .requestMatchers(/api/public/**).permitAll() .requestMatchers(/api/admin/**).hasAuthority(SCOPE_write) // 需要write权限 .anyRequest().authenticated() // 其他/api路径需要有效Token ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.decoder(jwtDecoder())) // 配置JWT解码器 ); return http.build(); } // 配置JWT解码器指向授权服务器的JWK Set端点 Bean public JwtDecoder jwtDecoder() { // 这里假设授权服务器运行在9000端口 String jwkSetUri http://localhost:9000/oauth2/jwks; return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build(); } }这个配置意味着所有访问/api/**的请求都会被资源服务器的安全过滤器拦截。请求头中必须包含Authorization: Bearer jwt-token。资源服务器会向http://localhost:9000/oauth2/jwks获取公钥并验证JWT的签名和有效期。验证通过后会从JWT的scope声明中提取权限如SCOPE_read,SCOPE_write用于后续的权限判断。4.2 在API中获取用户信息Token验证通过后我们如何在Controller中获取当前用户的信息呢Spring Security会自动将JWT中的声明注入到安全上下文中。import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.security.oauth2.jwt.Jwt; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(/api/user) public class UserController { GetMapping(/me) public MapString, Object getCurrentUserInfo(AuthenticationPrincipal Jwt jwt) { // Jwt对象包含了令牌的所有声明(claims) return Map.of( subject, jwt.getSubject(), // 用户标识通常是用户ID username, jwt.getClaimAsString(preferred_username), // 自定义声明 scopes, jwt.getClaimAsString(scope), issuedAt, jwt.getIssuedAt(), expiresAt, jwt.getExpiresAt() ); } GetMapping(/admin-data) public String getAdminData() { // 方法级安全控制可以通过PreAuthorize注解实现 return This is admin only data.; } }你也可以通过SecurityContextHolder来获取认证信息Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); // 获取用户名 Collection? extends GrantedAuthority authorities authentication.getAuthorities(); // 获取权限5. 实战测试与问题排查配置完成后我们如何进行端到端的测试这里以密码模式和客户端凭证模式为例使用curl命令进行测试。5.1 密码模式获取Token假设我们有一个用户用户名为user1密码为password存储在Spring Security的默认内存用户存储或你自己的UserDetailsService中。curl -X POST http://localhost:9000/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ # Basic Auth值是 test-client:secret 的Base64编码 -d grant_typepassword \ -d usernameuser1 \ -d passwordpassword \ -d scoperead write参数解释grant_typepassword指定密码模式。username/password资源所有者的凭证。scope请求的权限范围。Authorization: Basic ...客户端的身份凭证client_id:client_secret的Base64。成功响应{ access_token: eyJhbGciOiJSUzI1NiIs...很长的一串JWT..., token_type: Bearer, expires_in: 3599, scope: read write, refresh_token: eyJhbGciOiJSUzI1NiIs...另一个JWT用于刷新... }5.2 客户端凭证模式获取Token这种模式不需要用户参与。curl -X POST http://localhost:9000/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ -d grant_typeclient_credentials \ -d scoperead响应中将只包含access_token没有refresh_token。5.3 使用Token访问受保护API拿到access_token后就可以访问资源服务器的API了。curl -X GET http://localhost:8080/api/user/me \ -H Authorization: Bearer eyJhbGciOiJSUzI1NiIs...你的access_token...如果Token有效且权限足够你将收到用户信息。如果Token无效或过期你会收到401 Unauthorized错误。5.4 常见问题与排查技巧实录在实际整合中你几乎一定会遇到下面这些问题。我把它们和排查思路整理成了表格方便你快速对照。问题现象可能原因排查步骤与解决方案401 Unauthorized1. Token未提供或格式错误。2. Token已过期。3. Token签名验证失败资源服务器找不到或无法解析公钥。4. 访问的资源路径未被securityMatcher匹配走了默认的安全规则。1. 检查请求头是否为Authorization: Bearer token。2. 解码JWT可用 jwt.io 查看exp字段。3.重点检查资源服务器的jwkSetUri配置是否正确授权服务器的/oauth2/jwks端点是否能正常访问并返回正确的公钥集。4. 检查资源服务器的SecurityFilterChain的securityMatcher是否覆盖了你的API路径。403 Forbidden1. Token中的scope不满足访问所需权限。2. 用户角色权限不足。1. 检查JWT中的scope声明是否包含所需scope如write。2. 检查你的PreAuthorize注解或hasAuthority配置确保与Token中的声明匹配。注意权限前缀Spring Security默认会给scope加上SCOPE_前缀。授权服务器/oauth2/token端点返回400或invalid_grant1. 客户端认证失败client_id或client_secret错误。2. 不支持的授权类型grant_type。3. 重定向URI不匹配。4. 请求的scope未在客户端注册。1. 确认Basic Auth头中的client凭证正确且数据库中的client_secret存储的是加密后的值如示例中的BCrypt。2. 检查RegisteredClient的authorizationGrantTypes是否包含了你要用的模式如PASSWORD。3. 检查密码模式下的用户名密码是否正确对应的UserDetailsService能否找到用户。无法获取JWT中的自定义声明在资源服务器中JWT解码后默认只包含标准声明自定义声明需要通过JwtAuthenticationConverter转换。在资源服务器配置中自定义转换器javabr.oauth2ResourceServer(oauth2 - oauth2br .jwt(jwt - jwtbr .jwtAuthenticationConverter(jwtAuthenticationConverter())br )br)br在转换器中可以将JWT中的自定义声明如user_id,preferred_username提取并添加到Authentication的权限或属性中。整合后原有Spring Security表单登录失效配置了多个SecurityFilterChain且顺序或匹配规则冲突。使用Order注解明确每个SecurityFilterChain的优先级并使用securityMatcher精确控制每个过滤器链作用的请求路径避免重叠。通常授权服务器链Order值小匹配OAuth2端点默认链匹配其他路径如登录页。一个关键的实操心得遇到问题时打开Spring Security的调试日志是最高效的排查手段。在application.yml中添加logging.level.org.springframework.securityTRACE。这会打印出详细的过滤器链执行过程、认证决策、Token验证等信息你能清晰地看到请求走到了哪一步、为什么被拒绝。6. 进阶配置与生产环境考量上面的配置足以让你跑通一个演示环境。但要上生产还有几个关键点必须处理。6.1 使用JDBC存储授权信息之前我们只用JDBC存了客户端信息。授权过程中产生的授权码Authorization Code、Token等也需要持久化以防止服务器重启后数据丢失。Spring Authorization Server提供了对应的Schema。-- 授权表 CREATE TABLE oauth2_authorization ( id varchar(100) NOT NULL, registered_client_id varchar(100) NOT NULL, principal_name varchar(200) NOT NULL, authorization_grant_type varchar(100) NOT NULL, authorized_scopes varchar(1000) DEFAULT NULL, attributes blob DEFAULT NULL, state varchar(500) DEFAULT NULL, authorization_code_value blob DEFAULT NULL, authorization_code_issued_at timestamp DEFAULT NULL, authorization_code_expires_at timestamp DEFAULT NULL, authorization_code_metadata blob DEFAULT NULL, access_token_value blob DEFAULT NULL, access_token_issued_at timestamp DEFAULT NULL, access_token_expires_at timestamp DEFAULT NULL, access_token_metadata blob DEFAULT NULL, access_token_type varchar(100) DEFAULT NULL, access_token_scopes varchar(1000) DEFAULT NULL, oidc_id_token_value blob DEFAULT NULL, oidc_id_token_issued_at timestamp DEFAULT NULL, oidc_id_token_expires_at timestamp DEFAULT NULL, oidc_id_token_metadata blob DEFAULT NULL, refresh_token_value blob DEFAULT NULL, refresh_token_issued_at timestamp DEFAULT NULL, refresh_token_expires_at timestamp DEFAULT NULL, refresh_token_metadata blob DEFAULT NULL, PRIMARY KEY (id) );然后在配置类中注入JdbcOAuth2AuthorizationService和JdbcOAuth2AuthorizationConsentService即可Spring Boot会自动配置。6.2 配置令牌内省与吊销资源服务器除了用JWK Set验证JWT签名还可以通过令牌内省端点主动向授权服务器查询令牌状态。这对于撤销令牌如用户登出的场景非常有用。// 在资源服务器配置中可以配置内省如果不满足于JWT自验证 // 但通常JWT短有效期已足够内省会带来一次网络开销。 // .oauth2ResourceServer(oauth2 - oauth2 // .opaqueToken(opaque - opaque // .introspectionUri(http://auth-server:9000/oauth2/introspect) // .introspectionClientCredentials(resource-server-id, resource-server-secret) // ) // );吊销令牌的调用示例curl -X POST http://localhost:9000/oauth2/revoke \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ -d tokeneyJhbGciOiJSUzI1NiIs...要吊销的token... \ -d token_type_hintaccess_token6.3 密钥管理演示中我们用了代码生成的临时RSA密钥对。生产环境绝对不可以这样做你必须使用固定的密钥对通过openssl等工具生成将私钥private.key妥善保存在安全的秘密管理服务如HashiCorp Vault, AWS Secrets Manager中将公钥配置给授权服务器。定期轮换密钥制定密钥轮换策略。Spring Authorization Server支持配置多个JWKSource在新旧密钥交替期间可以同时支持用旧密钥签发的Token和新密钥签发的Token。分离签名和加密密钥如果涉及更复杂的OIDC场景可能需要对ID Token进行加密。// 示例从类路径加载PEM格式的密钥 Bean public JWKSourceSecurityContext jwkSource() throws Exception { String privateKeyPem ... // 从安全的地方读取私钥字符串 RSAPrivateKey privateKey ... // 解析PEM RSAPublicKey publicKey ... // 从私钥推导或单独读取公钥 RSAKey rsaKey new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(my-key-id-2024) .build(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); }6.4 关于Spring Security WebFlux的权限控制你提供的热词中提到了“yudao-cloud项目中flux流式输出与spring security的权限控制问题解析”。这指向了响应式编程栈。如果你的资源服务器使用的是Spring WebFlux那么配置方式会有所不同。核心区别在于你需要使用ServerSecurityContextRepository和ReactiveAuthenticationManager等响应式组件。SecurityFilterChain的配置Bean类型是ServerHttpSecurity而不是HttpSecurity。OAuth2资源服务器的配置器也换成了ServerHttpSecurity.OAuth2ResourceServerSpec。其核心思想是类似的只是API变成了响应式风格。例如配置JWT解码器Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http .authorizeExchange(exchanges - exchanges .pathMatchers(/api/public/**).permitAll() .anyExchange().authenticated() ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.jwtDecoder(reactiveJwtDecoder())) ); return http.build(); } Bean public ReactiveJwtDecoder reactiveJwtDecoder() { return NimbusReactiveJwtDecoder.withJwkSetUri(jwkSetUri).build(); }流式输出如SSE, WebFlux的Flux与权限控制的结合点在于确保在数据流开始推送之前用户的认证信息已经通过Security Context正确建立并且在流的整个生命周期内该安全上下文是有效的。这通常需要确保你的响应式数据源如MongoDB Reactive Streams driver, R2DBC的订阅操作发生在安全的反应式上下文ReactiveSecurityContextHolder中。整合Spring Security与OAuth2尤其是采用官方推荐的新架构是一个需要仔细理解各个组件角色和交互的过程。从简单的单体应用到复杂的微服务架构这套体系都能提供坚实的身份与授权基础。我的建议是先在测试环境中把密码模式和客户端凭证模式跑通理解Token的流动和验证过程然后再逐步引入授权码模式实现第三方登录最后再考虑密钥管理、高可用等生产级问题。每一步都做好日志记录和问题排查你会发现这套组合拳用熟了之后能帮你省去大量重复造轮子和解决安全漏洞的时间。
1. 项目概述为什么我们需要在Spring Security中整合OAuth2如果你正在构建一个需要用户登录的现代Web应用或API服务那么“登录”这件事本身就已经从一个简单的用户名密码校验演变成了一个复杂的系统工程。用户可能想用微信扫码登录你的网站开发者可能需要调用你的API来获取数据企业内部系统之间也需要安全地共享用户身份。当你的Spring Boot应用还在用着HttpSecurity配置表单登录为记住我Remember-Me和CSRF防护头疼时业界早已转向了更标准、更安全、也更灵活的解决方案——OAuth 2.0和OpenID Connect。“Spring Security整合OAuth2”这个标题听起来像是一个技术组件的拼接但它的本质是为你的应用引入一套工业级的身份认证与授权协议。Spring Security本身是一个强大的安全框架它负责“守卫大门”定义谁能进、能进到哪里。而OAuth2是一套标准协议它定义了“通行证”Token的颁发、校验和使用规则。将它们整合意味着你的应用不仅能用自己的账号体系资源所有者密码凭证模式登录更能轻松地接入微信、GitHub、Google等第三方登录授权码模式或者为移动端、前端SPA应用、微服务提供安全的API访问凭证客户端凭证模式、刷新令牌。我见过太多项目初期为了快把所有安全逻辑都写死在Controller里后期要加个第三方登录或者开放API就得伤筋动骨地重构。直接从Spring Security整合OAuth2开始看似前期配置稍多实则是为未来的扩展性买了一份保险。接下来我会以一个资源服务器提供API和授权服务器颁发Token分离的典型微服务架构为例带你从设计思路到踩坑细节完整走通整合流程。2. 架构设计与核心概念澄清在动手写代码之前我们必须把几个关键角色和流程掰扯清楚这是避免后续混乱的基础。很多人配置出错就是因为对这些概念的理解是模糊的。2.1 OAuth2的四种授权模式与适用场景OAuth2的核心是解决“在不分享用户密码的前提下让第三方应用获得有限的资源访问权限”。它定义了四种模式但在与Spring Security整合时我们最常用的是其中三种授权码模式这是最安全、最完整的流程用于有前端的Web应用。用户被重定向到授权服务器的登录页面登录并授权后授权服务器通过回调地址传回一个授权码前端再用这个码去换Token。这是第三方登录如“用GitHub登录”的标准流程。密码模式用户直接向客户端提供用户名和密码客户端用这些信息直接去授权服务器换Token。这要求你对客户端高度信任通常用于自家开发的第一方应用如自家的移动端App。由于需要传输密码安全性较低OAuth 2.1已建议弃用但在内部系统或遗留整合中仍可见。客户端凭证模式没有用户参与客户端用自己的client_id和client_secret直接获取Token。这用于服务器对服务器的通信比如微服务A要调用微服务B的某个后台作业API。简化模式Token直接通过前端回调URL的片段#后面传递跳过授权码步骤。用于纯前端SPA但因其安全性问题已被PKCE扩展的授权码模式所取代。在Spring Security OAuth2的体系中授权服务器负责实现这些模式的端点如/oauth/authorize,/oauth/token而资源服务器只负责验证Token并保护API。2.2 Spring Security OAuth2的两种实现方式与选型这里有一个历史性的关键选择。Spring官方对OAuth2的支持经历过一次重大变迁Spring Security OAuth项目这是一个独立的项目在Spring Boot 2.x时代是主流。它提供了EnableAuthorizationServer和EnableResourceServer注解来快速搭建。但是这个项目已经停止维护并将在未来版本中被移除。Spring Security 5.x 原生OAuth2支持从Spring Security 5开始OAuth2的支持被直接集成到核心框架中。它遵循更标准的规范配置方式更贴近Spring Security本身的DSL领域特定语言是当前及未来的推荐方案。我们今天的整合将完全基于Spring Security 5.x的原生支持。这意味着我们不会使用那些已废弃的注解而是通过配置SecurityFilterChainBean和一系列xxxConfigurer来构建我们的安全体系。这个选择确保了项目的长期可维护性。2.3 核心依赖引入基于Spring Boot 3.x和Spring Security 6.x其理念与5.x一脉相承你的pom.xml关键依赖如下dependencies !-- Spring Boot Web 基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring Security 核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency !-- OAuth2 资源服务器支持用于保护API -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-resource-server/artifactId /dependency !-- OAuth2 授权服务器支持用于颁发Token -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-authorization-server/artifactId /dependency !-- JWT支持推荐Token格式 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-resource-server/artifactId /dependency !-- 数据库存储用于存客户端信息、授权记录等 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies注意spring-boot-starter-oauth2-authorization-server是构建授权服务器的关键。如果你只是需要一个资源服务器比如一个只提供API的微服务那么只需要resource-server依赖即可。3. 构建授权服务器自己颁发Token授权服务器是整个OAuth2体系的核心它负责认证用户身份、征得用户同意并最终颁发访问令牌Access Token。我们将构建一个支持密码模式用于演示和客户端凭证模式的授权服务器。3.1 基础安全配置与端点暴露首先我们需要配置一个基础的SecurityFilterChain来保护授权服务器自身的端点。授权服务器的关键端点如/oauth2/authorize,/oauth2/token需要被暴露出来以供客户端访问但同时其管理界面可能需要额外保护。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; import org.springframework.security.config.Customizer; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; Configuration EnableWebSecurity public class DefaultSecurityConfig { Bean Order(1) // 设置较低的优先级确保先于授权服务器配置生效 public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authorize - authorize .requestMatchers(/actuator/health, /public/**).permitAll() // 公开端点 .anyRequest().authenticated() // 其他所有请求都需要认证 ) // 启用表单登录方便我们测试授权服务器的登录页面 .formLogin(Customizer.withDefaults()); return http.build(); } }3.2 配置授权服务器这是最关键的一步。我们将创建一个专门用于OAuth2授权服务的SecurityFilterChain并使用AuthorizationServerSettings来定制端点路径。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configurers.oauth2.server.authorization.OAuth2AuthorizationServerConfigurer; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configuration.OAuth2AuthorizationServerConfiguration; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configurers.OAuth2AuthorizationServerConfigurer; import org.springframework.security.oauth2.server.authorization.settings.AuthorizationServerSettings; import org.springframework.security.web.SecurityFilterChain; import org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint; import org.springframework.security.web.util.matcher.RequestMatcher; Configuration public class AuthorizationServerConfig { // 授权服务器本身的端点安全配置 Bean Order(2) // 优先级高于默认配置 public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception { // 应用OAuth2授权服务器的默认配置 OAuth2AuthorizationServerConfigurer authorizationServerConfigurer new OAuth2AuthorizationServerConfigurer(); // 自定义授权服务器端点请求匹配器 RequestMatcher endpointsMatcher authorizationServerConfigurer.getEndpointsMatcher(); http .securityMatcher(endpointsMatcher) // 只对授权服务器端点应用此配置 .authorizeHttpRequests(authorize - authorize .anyRequest().authenticated() ) .csrf(csrf - csrf.ignoringRequestMatchers(endpointsMatcher)) // 对OAuth2端点禁用CSRF .apply(authorizationServerConfigurer); // 应用授权服务器配置 // 当未认证用户访问受保护的授权端点时重定向到登录页 http.exceptionHandling(exceptions - exceptions .authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint(/login)) ); return http.build(); } // 配置授权服务器设置如端点路径 Bean public AuthorizationServerSettings authorizationServerSettings() { return AuthorizationServerSettings.builder() .issuer(http://auth-server:9000) // 发行者标识用于JWT的iss声明 .authorizationEndpoint(/oauth2/authorize) // 授权端点 .tokenEndpoint(/oauth2/token) // 令牌端点 .tokenIntrospectionEndpoint(/oauth2/introspect) // 令牌内省端点 .tokenRevocationEndpoint(/oauth2/revoke) // 令牌吊销端点 .jwkSetEndpoint(/oauth2/jwks) // JWK Set端点用于JWT .oidcUserInfoEndpoint(/userinfo) // OIDC用户信息端点 .build(); } }3.3 注册客户端与配置JWT客户端Client代表想要访问资源的应用程序。我们需要将客户端信息存储起来Spring Authorization Server支持内存和JDBC两种方式。为了持久化我们使用JDBC。同时我们将使用JWTJSON Web Token作为令牌格式因为它自包含、易于验证且无需服务端存储。3.3.1 数据库表结构初始化Spring Authorization Server提供了默认的SQL schema我们可以在src/main/resources下创建schema.sql-- 来自Spring Authorization Server官方示例 CREATE TABLE oauth2_registered_client ( id varchar(100) NOT NULL, client_id varchar(100) NOT NULL, client_id_issued_at timestamp DEFAULT CURRENT_TIMESTAMP NOT NULL, client_secret varchar(200) DEFAULT NULL, client_secret_expires_at timestamp DEFAULT NULL, client_name varchar(200) NOT NULL, client_authentication_methods varchar(1000) NOT NULL, authorization_grant_types varchar(1000) NOT NULL, redirect_uris varchar(1000) DEFAULT NULL, scopes varchar(1000) NOT NULL, client_settings varchar(2000) NOT NULL, token_settings varchar(2000) NOT NULL, PRIMARY KEY (id) );3.3.2 配置客户端存储与服务我们需要一个RegisteredClientRepositoryBean来管理客户端。这里我们在配置类中初始化一个客户端并存入数据库生产环境应从配置中心或管理界面动态添加。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.oauth2.core.AuthorizationGrantType; import org.springframework.security.oauth2.core.ClientAuthenticationMethod; import org.springframework.security.oauth2.core.oidc.OidcScopes; import org.springframework.security.oauth2.server.authorization.client.JdbcRegisteredClientRepository; import org.springframework.security.oauth2.server.authorization.client.RegisteredClient; import org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository; import org.springframework.security.oauth2.server.authorization.settings.ClientSettings; import org.springframework.security.oauth2.server.authorization.settings.TokenSettings; import javax.sql.DataSource; import java.time.Duration; import java.util.UUID; Configuration public class ClientConfig { Bean public RegisteredClientRepository registeredClientRepository(DataSource dataSource) { // 使用JDBC存储 JdbcRegisteredClientRepository repository new JdbcRegisteredClientRepository(dataSource); // 检查并初始化一个示例客户端仅用于演示生产环境不应硬编码 if (repository.findByClientId(test-client) null) { RegisteredClient registeredClient RegisteredClient.withId(UUID.randomUUID().toString()) .clientId(test-client) .clientSecret({bcrypt}$2a$10$NlqVU3h0mM.4AqV8pQwBZeZz7J5Kc1Xq5Ld7r2f5t0g1vH2s3j4k5l6) // 明文是 secret .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC) .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .authorizationGrantType(AuthorizationGrantType.CLIENT_CREDENTIALS) .authorizationGrantType(AuthorizationGrantType.PASSWORD) // 启用密码模式谨慎使用 .redirectUri(http://127.0.0.1:8080/login/oauth2/code/test-client) .scope(OidcScopes.OPENID) .scope(OidcScopes.PROFILE) .scope(read) .scope(write) .clientSettings(ClientSettings.builder().requireAuthorizationConsent(false).build()) // 跳过授权确认页 .tokenSettings(TokenSettings.builder() .accessTokenTimeToLive(Duration.ofHours(1)) // Access Token 1小时过期 .refreshTokenTimeToLive(Duration.ofDays(7)) // Refresh Token 7天过期 .reuseRefreshTokens(false) // 不重用Refresh Token .build()) .build(); repository.save(registeredClient); } return repository; } }3.3.3 配置JWT生成器为了让授权服务器能签发JWT格式的Token我们需要配置一个JWKSource。import com.nimbusds.jose.jwk.JWKSet; import com.nimbusds.jose.jwk.RSAKey; import com.nimbusds.jose.jwk.source.JWKSource; import com.nimbusds.jose.proc.SecurityContext; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.oauth2.jwt.JwtDecoder; import org.springframework.security.oauth2.server.authorization.config.annotation.web.configuration.OAuth2AuthorizationServerConfiguration; import java.security.KeyPair; import java.security.KeyPairGenerator; import java.security.NoSuchAlgorithmException; import java.security.interfaces.RSAPrivateKey; import java.security.interfaces.RSAPublicKey; import java.util.UUID; Configuration public class JwtConfig { Bean public JWKSourceSecurityContext jwkSource() throws NoSuchAlgorithmException { // 生成RSA密钥对。生产环境应从安全的密钥管理服务获取并妥善保管私钥。 KeyPairGenerator keyPairGenerator KeyPairGenerator.getInstance(RSA); keyPairGenerator.initialize(2048); KeyPair keyPair keyPairGenerator.generateKeyPair(); RSAPublicKey publicKey (RSAPublicKey) keyPair.getPublic(); RSAPrivateKey privateKey (RSAPrivateKey) keyPair.getPrivate(); // 构建RSA Key RSAKey rsaKey new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(UUID.randomUUID().toString()) .build(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); } // 授权服务器需要JWT解码器来解码自己签发的Token例如在令牌内省时 Bean public JwtDecoder jwtDecoder(JWKSourceSecurityContext jwkSource) { return OAuth2AuthorizationServerConfiguration.jwtDecoder(jwkSource); } }至此一个基本的授权服务器就配置完成了。它现在可以提供以下主要端点GET /oauth2/authorize授权端点用于授权码模式。POST /oauth2/token令牌端点用于获取所有类型的Token。POST /oauth2/introspect令牌内省端点验证Token有效性。POST /oauth2/revoke令牌吊销端点。GET /oauth2/jwks提供公钥集供资源服务器验证JWT签名。4. 构建资源服务器验证并保护API资源服务器是实际提供受保护API的服务。它不负责颁发Token只负责验证请求中携带的Token是否有效、是否具有访问特定资源的权限Scope。4.1 基础资源服务器配置资源服务器的配置相对简单核心是告诉它如何验证Token这里使用JWT并通过授权服务器发布的JWK Set端点验证签名。import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.oauth2.jwt.JwtDecoder; import org.springframework.security.oauth2.jwt.NimbusJwtDecoder; import org.springframework.security.web.SecurityFilterChain; Configuration EnableWebSecurity public class ResourceServerConfig { Bean public SecurityFilterChain resourceServerFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/api/**) // 只对/api/**路径应用此配置 .authorizeHttpRequests(authorize - authorize .requestMatchers(/api/public/**).permitAll() .requestMatchers(/api/admin/**).hasAuthority(SCOPE_write) // 需要write权限 .anyRequest().authenticated() // 其他/api路径需要有效Token ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.decoder(jwtDecoder())) // 配置JWT解码器 ); return http.build(); } // 配置JWT解码器指向授权服务器的JWK Set端点 Bean public JwtDecoder jwtDecoder() { // 这里假设授权服务器运行在9000端口 String jwkSetUri http://localhost:9000/oauth2/jwks; return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build(); } }这个配置意味着所有访问/api/**的请求都会被资源服务器的安全过滤器拦截。请求头中必须包含Authorization: Bearer jwt-token。资源服务器会向http://localhost:9000/oauth2/jwks获取公钥并验证JWT的签名和有效期。验证通过后会从JWT的scope声明中提取权限如SCOPE_read,SCOPE_write用于后续的权限判断。4.2 在API中获取用户信息Token验证通过后我们如何在Controller中获取当前用户的信息呢Spring Security会自动将JWT中的声明注入到安全上下文中。import org.springframework.security.core.annotation.AuthenticationPrincipal; import org.springframework.security.oauth2.jwt.Jwt; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(/api/user) public class UserController { GetMapping(/me) public MapString, Object getCurrentUserInfo(AuthenticationPrincipal Jwt jwt) { // Jwt对象包含了令牌的所有声明(claims) return Map.of( subject, jwt.getSubject(), // 用户标识通常是用户ID username, jwt.getClaimAsString(preferred_username), // 自定义声明 scopes, jwt.getClaimAsString(scope), issuedAt, jwt.getIssuedAt(), expiresAt, jwt.getExpiresAt() ); } GetMapping(/admin-data) public String getAdminData() { // 方法级安全控制可以通过PreAuthorize注解实现 return This is admin only data.; } }你也可以通过SecurityContextHolder来获取认证信息Authentication authentication SecurityContextHolder.getContext().getAuthentication(); String username authentication.getName(); // 获取用户名 Collection? extends GrantedAuthority authorities authentication.getAuthorities(); // 获取权限5. 实战测试与问题排查配置完成后我们如何进行端到端的测试这里以密码模式和客户端凭证模式为例使用curl命令进行测试。5.1 密码模式获取Token假设我们有一个用户用户名为user1密码为password存储在Spring Security的默认内存用户存储或你自己的UserDetailsService中。curl -X POST http://localhost:9000/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ # Basic Auth值是 test-client:secret 的Base64编码 -d grant_typepassword \ -d usernameuser1 \ -d passwordpassword \ -d scoperead write参数解释grant_typepassword指定密码模式。username/password资源所有者的凭证。scope请求的权限范围。Authorization: Basic ...客户端的身份凭证client_id:client_secret的Base64。成功响应{ access_token: eyJhbGciOiJSUzI1NiIs...很长的一串JWT..., token_type: Bearer, expires_in: 3599, scope: read write, refresh_token: eyJhbGciOiJSUzI1NiIs...另一个JWT用于刷新... }5.2 客户端凭证模式获取Token这种模式不需要用户参与。curl -X POST http://localhost:9000/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ -d grant_typeclient_credentials \ -d scoperead响应中将只包含access_token没有refresh_token。5.3 使用Token访问受保护API拿到access_token后就可以访问资源服务器的API了。curl -X GET http://localhost:8080/api/user/me \ -H Authorization: Bearer eyJhbGciOiJSUzI1NiIs...你的access_token...如果Token有效且权限足够你将收到用户信息。如果Token无效或过期你会收到401 Unauthorized错误。5.4 常见问题与排查技巧实录在实际整合中你几乎一定会遇到下面这些问题。我把它们和排查思路整理成了表格方便你快速对照。问题现象可能原因排查步骤与解决方案401 Unauthorized1. Token未提供或格式错误。2. Token已过期。3. Token签名验证失败资源服务器找不到或无法解析公钥。4. 访问的资源路径未被securityMatcher匹配走了默认的安全规则。1. 检查请求头是否为Authorization: Bearer token。2. 解码JWT可用 jwt.io 查看exp字段。3.重点检查资源服务器的jwkSetUri配置是否正确授权服务器的/oauth2/jwks端点是否能正常访问并返回正确的公钥集。4. 检查资源服务器的SecurityFilterChain的securityMatcher是否覆盖了你的API路径。403 Forbidden1. Token中的scope不满足访问所需权限。2. 用户角色权限不足。1. 检查JWT中的scope声明是否包含所需scope如write。2. 检查你的PreAuthorize注解或hasAuthority配置确保与Token中的声明匹配。注意权限前缀Spring Security默认会给scope加上SCOPE_前缀。授权服务器/oauth2/token端点返回400或invalid_grant1. 客户端认证失败client_id或client_secret错误。2. 不支持的授权类型grant_type。3. 重定向URI不匹配。4. 请求的scope未在客户端注册。1. 确认Basic Auth头中的client凭证正确且数据库中的client_secret存储的是加密后的值如示例中的BCrypt。2. 检查RegisteredClient的authorizationGrantTypes是否包含了你要用的模式如PASSWORD。3. 检查密码模式下的用户名密码是否正确对应的UserDetailsService能否找到用户。无法获取JWT中的自定义声明在资源服务器中JWT解码后默认只包含标准声明自定义声明需要通过JwtAuthenticationConverter转换。在资源服务器配置中自定义转换器javabr.oauth2ResourceServer(oauth2 - oauth2br .jwt(jwt - jwtbr .jwtAuthenticationConverter(jwtAuthenticationConverter())br )br)br在转换器中可以将JWT中的自定义声明如user_id,preferred_username提取并添加到Authentication的权限或属性中。整合后原有Spring Security表单登录失效配置了多个SecurityFilterChain且顺序或匹配规则冲突。使用Order注解明确每个SecurityFilterChain的优先级并使用securityMatcher精确控制每个过滤器链作用的请求路径避免重叠。通常授权服务器链Order值小匹配OAuth2端点默认链匹配其他路径如登录页。一个关键的实操心得遇到问题时打开Spring Security的调试日志是最高效的排查手段。在application.yml中添加logging.level.org.springframework.securityTRACE。这会打印出详细的过滤器链执行过程、认证决策、Token验证等信息你能清晰地看到请求走到了哪一步、为什么被拒绝。6. 进阶配置与生产环境考量上面的配置足以让你跑通一个演示环境。但要上生产还有几个关键点必须处理。6.1 使用JDBC存储授权信息之前我们只用JDBC存了客户端信息。授权过程中产生的授权码Authorization Code、Token等也需要持久化以防止服务器重启后数据丢失。Spring Authorization Server提供了对应的Schema。-- 授权表 CREATE TABLE oauth2_authorization ( id varchar(100) NOT NULL, registered_client_id varchar(100) NOT NULL, principal_name varchar(200) NOT NULL, authorization_grant_type varchar(100) NOT NULL, authorized_scopes varchar(1000) DEFAULT NULL, attributes blob DEFAULT NULL, state varchar(500) DEFAULT NULL, authorization_code_value blob DEFAULT NULL, authorization_code_issued_at timestamp DEFAULT NULL, authorization_code_expires_at timestamp DEFAULT NULL, authorization_code_metadata blob DEFAULT NULL, access_token_value blob DEFAULT NULL, access_token_issued_at timestamp DEFAULT NULL, access_token_expires_at timestamp DEFAULT NULL, access_token_metadata blob DEFAULT NULL, access_token_type varchar(100) DEFAULT NULL, access_token_scopes varchar(1000) DEFAULT NULL, oidc_id_token_value blob DEFAULT NULL, oidc_id_token_issued_at timestamp DEFAULT NULL, oidc_id_token_expires_at timestamp DEFAULT NULL, oidc_id_token_metadata blob DEFAULT NULL, refresh_token_value blob DEFAULT NULL, refresh_token_issued_at timestamp DEFAULT NULL, refresh_token_expires_at timestamp DEFAULT NULL, refresh_token_metadata blob DEFAULT NULL, PRIMARY KEY (id) );然后在配置类中注入JdbcOAuth2AuthorizationService和JdbcOAuth2AuthorizationConsentService即可Spring Boot会自动配置。6.2 配置令牌内省与吊销资源服务器除了用JWK Set验证JWT签名还可以通过令牌内省端点主动向授权服务器查询令牌状态。这对于撤销令牌如用户登出的场景非常有用。// 在资源服务器配置中可以配置内省如果不满足于JWT自验证 // 但通常JWT短有效期已足够内省会带来一次网络开销。 // .oauth2ResourceServer(oauth2 - oauth2 // .opaqueToken(opaque - opaque // .introspectionUri(http://auth-server:9000/oauth2/introspect) // .introspectionClientCredentials(resource-server-id, resource-server-secret) // ) // );吊销令牌的调用示例curl -X POST http://localhost:9000/oauth2/revoke \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: Basic dGVzdC1jbGllbnQ6c2VjcmV0 \ -d tokeneyJhbGciOiJSUzI1NiIs...要吊销的token... \ -d token_type_hintaccess_token6.3 密钥管理演示中我们用了代码生成的临时RSA密钥对。生产环境绝对不可以这样做你必须使用固定的密钥对通过openssl等工具生成将私钥private.key妥善保存在安全的秘密管理服务如HashiCorp Vault, AWS Secrets Manager中将公钥配置给授权服务器。定期轮换密钥制定密钥轮换策略。Spring Authorization Server支持配置多个JWKSource在新旧密钥交替期间可以同时支持用旧密钥签发的Token和新密钥签发的Token。分离签名和加密密钥如果涉及更复杂的OIDC场景可能需要对ID Token进行加密。// 示例从类路径加载PEM格式的密钥 Bean public JWKSourceSecurityContext jwkSource() throws Exception { String privateKeyPem ... // 从安全的地方读取私钥字符串 RSAPrivateKey privateKey ... // 解析PEM RSAPublicKey publicKey ... // 从私钥推导或单独读取公钥 RSAKey rsaKey new RSAKey.Builder(publicKey) .privateKey(privateKey) .keyID(my-key-id-2024) .build(); JWKSet jwkSet new JWKSet(rsaKey); return (jwkSelector, securityContext) - jwkSelector.select(jwkSet); }6.4 关于Spring Security WebFlux的权限控制你提供的热词中提到了“yudao-cloud项目中flux流式输出与spring security的权限控制问题解析”。这指向了响应式编程栈。如果你的资源服务器使用的是Spring WebFlux那么配置方式会有所不同。核心区别在于你需要使用ServerSecurityContextRepository和ReactiveAuthenticationManager等响应式组件。SecurityFilterChain的配置Bean类型是ServerHttpSecurity而不是HttpSecurity。OAuth2资源服务器的配置器也换成了ServerHttpSecurity.OAuth2ResourceServerSpec。其核心思想是类似的只是API变成了响应式风格。例如配置JWT解码器Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http .authorizeExchange(exchanges - exchanges .pathMatchers(/api/public/**).permitAll() .anyExchange().authenticated() ) .oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt.jwtDecoder(reactiveJwtDecoder())) ); return http.build(); } Bean public ReactiveJwtDecoder reactiveJwtDecoder() { return NimbusReactiveJwtDecoder.withJwkSetUri(jwkSetUri).build(); }流式输出如SSE, WebFlux的Flux与权限控制的结合点在于确保在数据流开始推送之前用户的认证信息已经通过Security Context正确建立并且在流的整个生命周期内该安全上下文是有效的。这通常需要确保你的响应式数据源如MongoDB Reactive Streams driver, R2DBC的订阅操作发生在安全的反应式上下文ReactiveSecurityContextHolder中。整合Spring Security与OAuth2尤其是采用官方推荐的新架构是一个需要仔细理解各个组件角色和交互的过程。从简单的单体应用到复杂的微服务架构这套体系都能提供坚实的身份与授权基础。我的建议是先在测试环境中把密码模式和客户端凭证模式跑通理解Token的流动和验证过程然后再逐步引入授权码模式实现第三方登录最后再考虑密钥管理、高可用等生产级问题。每一步都做好日志记录和问题排查你会发现这套组合拳用熟了之后能帮你省去大量重复造轮子和解决安全漏洞的时间。
)
