Spring Boot 如何整合 Spring Security EnableOpenIDConnect 实现单点登录？

在微服务架构下，将 Spring Boot 应用接入统一的身份提供商已经成了基础需求。OpenID Connect 基于 OAuth2 扩展了身份层，而 Spring Security 从 5.2 版本开始提供的 @EnableOpenIDConnect 注解，可以让客户端自动具备 OIDC 发现、授权码流转和 id_token 校验能力。理解它与普通 OAuth2 客户端注解的差异，是写出稳定单点登录代码的前提。

依赖引入与基础注解配置

要在 Spring Boot 中开启 OIDC 客户端，首先需要在构建文件中引入 spring-security-oauth2-client 模块。该模块内部已经包含了处理 OIDC 发现文档（/.well-known/openid-configuration）的客户端实现，配合 @EnableOpenIDConnect 后，Spring 会自动注册对应的 ClientRegistrationRepository 和重定向过滤器。很多初学者误以为只要加了注解就能直接用，实际上还需要在配置文件中声明 issuer-uri，否则框架无法获知认证服务器的元数据地址。

下面是一段典型的 Maven 依赖与启动类写法。注意 @EnableOpenIDConnect 一般放在带有 @Configuration 的类上，而不是主启动类，这样更利于测试时覆盖配置。issuer-uri 必须以 https 开头且可达，框架在应用启动阶段就会发起一次发现请求，若网络不通会导致上下文初始化失败。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

@Configuration
@EnableOpenIDConnect
public class OidcConfig {
    // 此处无需手动定义 ClientRegistrationRepository
    // 框架会根据 spring.security.oauth2.client.registration.* 自动装配
}

配置文件中需要写明注册信息。以授权码模式为例，registration 名称自定义为 myclient，provider 指向同一个逻辑名，并填写 issuer-uri。这样 EnableOpenIDConnect 才能把授权端点、令牌端点和 jwk-set-uri 全部从发现文档中解析出来，省去手工维护多套 URL 的麻烦。

spring.security.oauth2.client.registration.myclient.client-id=app-a
spring.security.oauth2.client.registration.myclient.client-secret=secret-a
spring.security.oauth2.client.registration.myclient.scope=openid,profile,email
spring.security.oauth2.client.registration.myclient.redirect-uri={baseUrl}/login/oauth2/code/myclient
spring.security.oauth2.client.provider.myclient.issuer-uri=https://idp.ippipp.com/realms/demo

安全过滤器链与回调处理

开启 @EnableOpenIDConnect 后，Spring Security 会向过滤器链中插入 OAuth2LoginAuthenticationFilter 和对应的认证成功处理器。我们需要通过 SecurityFilterChain Bean 显式放行登录相关路径，并对业务接口做认证保护。一个常见错误是把回调路径配成了前端网关地址，而后端实际 baseUrl 是内网域名，导致认证服务器携带的 state 参数在跳转回来时无法被同一会话识别，最终抛出 ClientRegistration 不匹配异常。

下面的 Java 配置展示了如何编排过滤器链。注意 authorizeHttpRequests 中把 /login/** 和 /oauth2/** 设为 permitAll，其余请求必须经过认证。同时调用 oauth2Login() 开启默认的登录流程，该方法在 EnableOpenIDConnect 存在时会自动使用 OIDC 专用的认证转换器，从而正确解析 id_token 中的 iss 和 aud 声明。

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/login/**", "/oauth2/**").permitAll()
            .anyRequest().authenticated()
        )
        .oauth2Login(oauth -> oauth
            .redirectionEndpoint(red -> red
                .baseUri("/login/oauth2/code/*"))
        );
    return http.build();
}

在控制器层获取用户信息时，推荐注入 OAuth2AuthenticationToken 而不是自行解析令牌字符串。框架已经把 id_token 中的标准声明映射为 OAuth2User 属性，你可以直接读取 name 和 preferred_username。如果业务需要把登录态透传到下游服务，应当把 access_token 存入 Session 或转发头，而不是把整个 id_token 透传，因为 id_token 仅用于身份认证，不应作为资源访问凭证。

@GetMapping("/profile")
public Map<String, Object> profile(OAuth2AuthenticationToken token) {
    OAuth2User user = token.getPrincipal();
    Map<String, Object> map = new HashMap<>();
    map.put("name", user.getAttribute("preferred_username"));
    map.put("email", user.getAttribute("email"));
    return map;
}

多租户场景下的 Issuer 动态解析

当一套 Spring Boot 后端要服务多个企业租户，而每个租户使用不同的 OIDC issuer 时，写死 provider 配置就不再适用。@EnableOpenIDConnect 本身不限制 issuer 数量，但需要自定义 ClientRegistrationRepository 实现，根据请求域名或路径前缀动态返回对应的 ClientRegistration。此时要小心 JWK 签名密钥的缓存失效问题：若某个租户的认证服务器轮换了签名证书，而本地缓存未过期，就会校验失败导致全员登出。

解决思路是提供一个基于租户标识的惰性加载仓库。以下示例在内存中维护 Map，首次访问某租户时根据传入的 issuer-uri 调用 ClientRegistrations.fromIssuerLocation 构建对象并缓存。同时建议把 JwtDecoder 的密钥缓存时间设为略短于认证服务器的证书生命周期，并捕获 SignatureException 后触发一次刷新，避免硬失败。

@Component
public class TenantRegistrationRepository implements ClientRegistrationRepository {
    private final Map<String, ClientRegistration> cache = new ConcurrentHashMap<>();

    @Override
    public ClientRegistration findByRegistrationId(String registrationId) {
        return cache.computeIfAbsent(registrationId, id -> {
            String issuer = "https://idp.ippipp.com/realms/" + id;
            return ClientRegistrations.fromIssuerLocation(issuer)
                .registrationId(id)
                .clientId("app-a")
                .clientSecret("secret-a")
                .build();
        });
    }
}

动态仓库接入后，仍要保留 @EnableOpenIDConnect 以激活 OIDC 特有的认证逻辑，只是把原本自动装配的仓库替换成了自定义实现。在网关层，可以通过子域名 tenant1.app.com 与 tenant2.app.com 区分租户，并在转发请求头中带上 X-Tenant-Id，后端根据此头选择 registrationId。这样既能复用同一套过滤器链，又能隔离各租户的登录态与令牌签名体系，在保障安全的同时降低运维复杂度。

Spring BootEnableOpenIDConnect单点登录修改时间：2026-08-25 14:31:02