Spring Boot 3.4 Starter中SecurityFilterChain配置冲突求助

问题背景 #

开发Spring Boot 3.4 Starter，目标是实现开箱即用的安全配置，包含认证提供者、转换器、认证管理器及SecurityFilterChain，无需用户手动添加@EnableWebSecurity。目前其他配置均可正常集成，但自定义SecurityFilterChain会与默认的defaultSecurityFilterChain或Actuator的managementSecurityFilterChain冲突。观察到ManagementWebSecurityAutoConfiguration和默认defaultSecurityFilterChain均依赖@ConditionalOnDefaultWebSecurity注解，尝试通过@AutoConfigureBefore(SecurityAutoConfiguration.class)调整自动配置顺序后，仍出现以下错误：

用户代码示例 #

@Configuration
@ConditionalOnClass(EnableWebSecurity.class) 
@AutoConfigureBefore(SecurityAutoConfiguration.class)
public class MySecurityConfiguration {
    // 其他配置Bean
    
    @Bean
    public SecurityFilterChain securityFilterChain(...) {
        // 自定义安全过滤器链配置
        ...
    }
}

错误信息（已翻译） #

已经配置了匹配任意请求的过滤器链[定义为'managementSecurityFilterChain'的DefaultSecurityFilterChain]，这意味着这个过滤器链[定义为'securityFilterChain'的DefaultSecurityFilterChain]永远不会被调用。请使用HttpSecurity#securityMatcher确保只有一个过滤器链配置为'任意请求'，并且'任意请求'的过滤器链最后发布。

解决方案 #

方案1：禁用默认安全配置，替代为自定义过滤器链 #

通过@ConditionalOnDefaultWebSecurity(false)禁用默认的defaultSecurityFilterChain，确保自定义过滤器链成为唯一的全局安全配置：

@Configuration
@ConditionalOnClass(EnableWebSecurity.class)
@AutoConfigureBefore(SecurityAutoConfiguration.class)
@ConditionalOnDefaultWebSecurity(false) // 核心：禁用默认全局安全配置
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/**") // 明确匹配所有请求路径
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            )
            // 配置自定义认证提供者、转换器、认证管理器等
            ;
        return http.build();
    }

    // 其他自定义安全Bean：认证提供者、转换器等
}

若需统一管理Actuator端点的安全规则，可在Starter的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件中排除Actuator的默认安全配置：

com.yourpackage.MySecurityConfiguration
!org.springframework.boot.actuate.autoconfigure.security.servlet.ManagementWebSecurityAutoConfiguration

方案2：通过securityMatcher划分路径范围 #

如果不需要覆盖全局安全配置，仅让自定义过滤器链处理特定业务路径（如/api/**），避免与默认或Actuator的过滤器链冲突：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .securityMatcher("/api/**") // 仅匹配业务API路径
        .authorizeHttpRequests(auth -> auth
            .anyRequest().authenticated()
        )
        // 自定义安全配置
        ;
    return http.build();
}

此时默认defaultSecurityFilterChain处理非API/非Actuator路径，managementSecurityFilterChain处理/actuator/**路径，三者互不冲突。

核心原理 #

• @ConditionalOnDefaultWebSecurity：仅当不存在自定义SecurityFilterChain或@EnableWebSecurity注解时，默认安全配置才会生效。设置@ConditionalOnDefaultWebSecurity(false)可直接禁用默认的defaultSecurityFilterChain。
• Spring Security过滤器链匹配规则：请求会被第一个匹配的过滤器链处理，因此不能存在多个匹配/**的过滤器链，必须通过securityMatcher明确每个过滤器链的路径范围，或确保全局过滤器链唯一且最后注册。

内容的提问来源于stack exchange，提问作者Magnus Persson