Spring Boot 整合 Spring Authorization Server 搭建认证中心要注意哪些细节？

Spring Security团队早已停止对旧版OAuth2授权服务器模块的维护，转而推出了全新的Spring Authorization Server项目。对于正在搭建微服务认证体系的团队来说，这套新框架是官方指定的替代方案。它完整实现了OAuth 2.1和OpenID Connect 1.0规范，与Spring Boot的整合方式也与旧版有较大差异。本文基于Spring Boot 3.x版本，带你从零搭建一个可用的认证中心，并梳理整合过程中必须注意的细节。

一、环境准备与核心依赖引入

搭建认证中心的第一步是选对版本。Spring Authorization Server要求JDK 17以上、Spring Boot 3.x系列版本，如果项目还停留在Spring Boot 2.x，需要先升级基础环境，否则会出现类找不到、自动装配失效等问题。推荐使用Spring Boot官方提供的脚手架生成项目骨架，再手动添加授权服务器依赖。

核心依赖只有一个starter，不需要再单独引入spring-security相关包，因为授权服务器模块已经传递依赖了Security。pom.xml中的关键配置如下：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-authorization-server</artifactId>
</dependency>

需要注意版本匹配问题。Spring Boot 3.1之后，官方直接提供了上述starter，而在3.1之前的版本中，需要手动引入spring-security-oauth2-authorization-server并自行管理版本号。混用不同版本的授权服务器与Security核心包，是新手最容易犯的错误，典型表现是启动时报NoSuchMethodError。建议始终通过Spring Boot的依赖管理来控制版本，不要在dependencyManagement里随意锁定Security版本。

二、配置授权服务器与客户端信息

Spring Authorization Server的核心配置围绕一个SecurityFilterChain展开。与旧版通过继承AuthorizationServerConfigurerAdapter的写法完全不同，新版采用声明式的Bean装配风格。最简配置包括三部分：授权服务器过滤器链、客户端信息注册、JWK密钥源。下面是一个可运行的完整示例：

@Configuration
@EnableWebSecurity
public class AuthServerConfig {

    @Bean
    @Order(1)
    public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
        OAuth2AuthorizationServerConfigurer configurer =
                OAuth2AuthorizationServerConfigurer.authorizationServer();

        http
            .securityMatcher(configurer.getEndpointsMatcher())
            .with(configurer, (server) -> server.tokenGenerator(passwordTokenGenerator()))
            .authorizeHttpRequests((authorize) -> authorize.anyRequest().authenticated())
            .formLogin(Customizer.withDefaults());
        return http.build();
    }

    @Bean
    @Order(2)
    public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests((authorize) -> authorize
                .anyRequest().authenticated())
            .formLogin(Customizer.withDefaults());
        return http.build();
    }

    @Bean
    public RegisteredClientRepository registeredClientRepository() {
        RegisteredClient client = RegisteredClient.withId(UUID.randomUUID().toString())
                .clientId("demo-client")
                .clientSecret("{noop}demo-secret")
                .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
                .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
                .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN)
                .redirectUri("http://127.0.0.1:9000/login/oauth2/code/demo-client-oidc")
                .scope(OidcScopes.OPENID)
                .scope("read")
                .clientSettings(ClientSettings.builder().requireAuthorizationConsent(true).build())
                .tokenSettings(TokenSettings.builder().accessTokenTimeToLive(Duration.ofMinutes(30)).build())
                .build();
        return new InMemoryRegisteredClientRepository(client);
    }

    @Bean
    public JWKSource<SecurityContext> jwkSource() {
        KeyPair keyPair = generateRsaKey();
        RSAPublicKey publicKey = (RSAPublicKey) keyPair.getPublic();
        RSAPrivateKey privateKey = (RSAPrivateKey) keyPair.getPrivate();
        RSAKey rsaKey = new RSAKey.Builder(publicKey)
                .privateKey(privateKey)
                .keyID(UUID.randomUUID().toString())
                .build();
        JWKSet jwkSet = new JWKSet(rsaKey);
        return new ImmutableJWKSet<>(jwkSet);
    }

    private static KeyPair generateRsaKey() {
        try {
            KeyPairGenerator generator = KeyPairGenerator.getInstance("RSA");
            generator.initialize(2048);
            return generator.generateKeyPair();
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }
}

这里有几个必须留意的点。第一，两条SecurityFilterChain必须用@Order明确排序，授权服务器的链条要排在前面，否则默认的安全链会抢先拦截所有请求，导致授权端点404。第二，客户端密码必须使用密码编码器格式前缀，例如{noop}或{bcrypt}，直接写明文会在认证时报编码器找不到的错误。第三，重定向地址必须与客户端应用中注册的回调完全一致，包括路径和端口，差一个字符都会跳转到错误页面。

三、令牌签发与密钥管理的正确姿势

上面示例中的JWKSource用的是内存生成密钥，这在开发阶段没问题，但一旦服务重启，密钥就变了，之前签发的JWT全部失效，用户被迫重新登录。生产环境必须把密钥持久化，常见做法有两种：一是把JKS或PEM格式的密钥文件放在服务器固定目录，启动时加载；二是使用KMS等云密钥管理服务。推荐将密钥路径配置在application.yml中，通过@Value注入读取。

@Value("${auth.jwk-path}")
private Resource jwkResource;

@Bean
public JWKSource<SecurityContext> jwkSource() throws Exception {
    // 从配置路径加载持久化的RSA密钥，避免重启后密钥变化
    KeyStore ks = KeyStore.getInstance("JKS");
    ks.getInputStream().readAllBytes();
    ks.load(jwkResource.getInputStream(), "storepass".toCharArray());
    RSAPublicKey publicKey = (RSAPublicKey) ks.getCertificate("auth-key").getPublicKey();
    RSAPrivateKey privateKey = (RSAPrivateKey) ks.getKey("auth-key", "keypass".toCharArray());
    RSAKey rsaKey = new RSAKey.Builder(publicKey)
            .privateKey(privateKey)
            .keyID("auth-key-1")
            .build();
    return new ImmutableJWKSet<>(new JWKSet(rsaKey));
}

密钥文件本身也要妥善保护，文件权限收紧到服务运行用户可读即可，绝对不能提交到代码仓库。另外一个容易被忽视的问题是密钥轮换：JWKSource返回的JWKSet可以包含多个密钥，签发使用最新的，验证时新旧密钥同时可用，这样轮换密钥时旧令牌不会立刻失效，实现平滑过渡。

除了密钥，授权数据（Authorization）和客户端信息的存储也要考虑持久化。框架默认提供InMemoryOAuth2AuthorizationService，重启后所有已授权记录、刷新令牌都会丢失。生产环境应实现OAuth2AuthorizationService接口，把授权数据存到数据库或Redis中。存Redis时要设置与令牌有效期一致的过期时间，否则会造成内存泄漏。

四、资源服务器对接与联调验证

认证中心搭好后，业务服务作为资源服务器接入。资源服务只需引入spring-boot-starter-oauth2-resource-server，然后在配置文件里指向认证中心的JWKS地址即可完成验签配置：

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://127.0.0.1:9000/oauth2/jwks

资源服务器收到请求后，会根据JWT头中的kid找到对应公钥进行验签，全程不需要调用认证中心的接口校验令牌，这就是JWT方案在微服务场景下的性能优势。如果需要根据scope或自定义声明做权限控制，可以在SecurityFilterChain中配置jwtAuthenticationConverter，把令牌中的声明映射为Spring Security的权限集合。

联调阶段建议用开放平台的标准流程手动走一遍授权码模式：先访问认证中心的/oauth2/authorize端点，登录并同意授权后拿到code，再用code换取access_token，最后携带令牌调用资源服务接口。全流程验证通过后，再编写自动化测试。排查问题时，把Security相关日志级别调到DEBUG能看到每个过滤器的处理过程，绝大多数401问题都能从中找到线索。

总结来说，Spring Boot整合Spring Authorization Server的门槛并不高，关键在于理清过滤器链的顺序、密钥的持久化管理和令牌存储的持久化方案这三件事。把开发环境的默认实现替换为生产级实现，再补上登录页美化和用户体系对接，一套认证中心就可以正式对外服务了。

Spring BootSpring Authorization ServerOAuth2认证中心修改时间：2026-09-03 23:54:43