Spring Security过滤器顺序与JWT认证控制

理解Spring Security过滤器链与执行顺序

Spring Security通过一系列的Filter来构建其安全机制，这些过滤器按照特定的顺序依次执行，共同处理HTTP请求。当我们需要引入自定义的业务逻辑（例如多租户上下文设置）时，如果这些逻辑依赖于请求的初始状态或需要在安全验证之前完成，那么自定义过滤器的执行顺序就变得至关重要。

以多租户场景为例，一个TenantFilter可能需要根据请求头中的租户标识来设置当前请求的数据库连接字符串。如果这个过滤器在JWT认证/授权过滤器之后执行，那么当JWT过滤器尝试从数据库加载用户信息进行认证时，可能会因为连接到错误的数据库或无法连接而失败。

问题示例：自定义TenantFilter与JWT过滤器的冲突

假设我们有一个TenantFilter用于设置租户相关的数据库连接：

@Component // 确保Spring能够发现并管理此过滤器
public class TenantFilter extends OncePerRequestFilter {
    private static final Logger logger = LoggerFactory.getLogger(TenantFilter.class);
    private static final String TENANT_HEADER = "X-Tenant";

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String tenantId = request.getHeader(TENANT_HEADER);
        if (tenantId != null && !tenantId.isEmpty()) {
            // 示例：根据租户ID设置连接字符串或租户上下文
            String dbConnectionString = "jdbc:mysql://localhost:3306/" + tenantId + "?useSSL=false";
            ConnectionStorage.setConnection(dbConnectionString); // 假设ConnectionStorage是一个线程局部变量
            logger.info("TenantFilter: Set connection for tenant: {}", tenantId);
        } else {
            logger.warn("TenantFilter: No X-Tenant header found.");
        }
        try {
            filterChain.doFilter(request, response);
        } finally {
            ConnectionStorage.clear(); // 清理租户上下文
            logger.info("TenantFilter: Cleared connection.");
        }
    }
}

同时，我们有自定义的JwtAuthenticationFilter（用于登录时生成JWT）和JwtAuthorizationFilter（用于后续请求验证JWT）：

// JwtAuthenticationFilter (用于处理 /api/user/login 并生成JWT)
public class JwtAuthenticationFilter extends UsernamePasswordAuthenticationFilter {
    // ... 构造器和attemptAuthentication, successfulAuthentication 方法 ...
    // attemptAuthentication 会尝试从数据库加载用户，此时就需要正确的租户连接
}

// JwtAuthorizationFilter (用于验证后续请求的JWT)
public class JwtAuthorizationFilter extends BasicAuthenticationFilter {
    // ... 构造器和doFilterInternal, getAuthentication 方法 ...
    // getAuthentication 可能会从数据库加载用户，此时也需要正确的租户连接
}

如果TenantFilter的执行顺序在JwtAuthenticationFilter或JwtAuthorizationFilter之后，那么在JWT过滤器尝试进行认证或授权时，可能无法获取到正确的租户上下文，导致认证失败。

解决方案：控制过滤器执行顺序

Spring Security提供了多种方式来控制自定义过滤器的执行顺序。

1. 使用@Order注解

@Order注解是Spring框架提供的一种通用机制，用于指定组件的排序。对于过滤器，我们可以通过它来影响其在整个Web应用过滤器链中的位置。

import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

// ... 其他导入 ...

@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // 确保此过滤器具有最高的优先级
public class TenantFilter extends OncePerRequestFilter {
    // ... 过滤器实现 ...
}

Ordered.HIGHEST_PRECEDENCE代表了Integer.MIN_VALUE，这意味着它拥有最高的优先级，通常会比大多数Spring Security的内置过滤器更早执行。

注意事项：

• @Order注解通常用于在Spring容器中注册的过滤器。
• Ordered.HIGHEST_PRECEDENCE会使过滤器尽可能早地执行，但这并不总是能保证其在Spring Security 内部 过滤器链中的精确位置。对于更精细的控制，我们可能需要结合SecurityFilterChain配置。

2. 通过SecurityFilterChain精确插入过滤器

对于Spring Security 5.x及更高版本，推荐使用SecurityFilterChain（通过WebSecurityConfigurerAdapter的configure(HttpSecurity http)方法，或直接定义SecurityFilterChain Bean）来配置安全过滤器链。这提供了最精确的过滤器插入控制。

我们可以使用http.addFilterBefore()或http.addFilterAt()方法将自定义过滤器放置在Spring Security过滤器链中的特定位置。

首先，确保你的TenantFilter是一个Spring Bean，但不要直接将其标记为@Component或@Order，因为我们希望通过SecurityFilterChain来管理它的生命周期和位置，而不是让它作为独立的Servlet Filter注册。

// TenantFilter.java (不带@Component或@Order)
public class TenantFilter extends OncePerRequestFilter {
    // ... 过滤器实现 ...
}

然后，在你的Spring Security配置类中（例如，一个继承自WebSecurityConfigurerAdapter的类，或者一个配置SecurityFilterChain Bean的类）：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.security.web.authentication.www.BasicAuthenticationFilter;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    // 假设你有自定义的UserDetailsService和PasswordEncoder
    // @Autowired
    // private UserDetailsService userDetailsService;
    // @Autowired
    // private PasswordEncoder passwordEncoder;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // 实例化你的自定义过滤器
        TenantFilter tenantFilter = new TenantFilter(); // 如果TenantFilter有依赖，需要通过构造器注入或Spring上下文获取

        // JwtAuthenticationFilter需要AuthenticationManager
        // JwtAuthenticationFilter jwtAuthenticationFilter = new JwtAuthenticationFilter(authenticationManagerBean());
        // jwtAuthenticationFilter.setFilterProcessesUrl("/api/user/login"); // 设置登录URL

        // JwtAuthorizationFilter也需要AuthenticationManager
        // JwtAuthorizationFilter jwtAuthorizationFilter = new JwtAuthorizationFilter(authenticationManagerBean());

        http.csrf().disable() // 禁用CSRF
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 无状态会话
            .and()
            .authorizeRequests()
                .antMatchers("/api/user/login").permitAll() // 允许登录接口访问
                .anyRequest().authenticated() // 其他所有请求都需要认证
            .and()
            // 关键步骤：在Spring Security的任何过滤器之前添加TenantFilter
            // UsernamePasswordAuthenticationFilter 是 Spring Security 认证流程的早期过滤器
            // BasicAuthenticationFilter 也是认证/授权流程的早期过滤器
            // 你可以选择一个合适的内置过滤器作为锚点
            .addFilterBefore(tenantFilter, UsernamePasswordAuthenticationFilter.class)
            // .addFilterBefore(tenantFilter, BasicAuthenticationFilter.class) // 也可以选择在BasicAuthenticationFilter之前

            // 添加你的JWT认证过滤器 (如果需要自定义)
            // .addFilter(jwtAuthenticationFilter) // 如果是自定义的UsernamePasswordAuthenticationFilter，直接addFilter即可
            // .addFilterBefore(jwtAuthorizationFilter, UsernamePasswordAuthenticationFilter.class); // JwtAuthorizationFilter通常在认证之后，但需要在其他安全检查之前
            ;

        // 推荐：使用Spring Security内置的JWT/OAuth2支持，而不是自定义实现
        // 如果使用Spring Security的OAuth2资源服务器，配置会更简洁
        // http.oauth2ResourceServer().jwt();
    }

    // Spring Security 5.7+ 推荐通过SecurityFilterChain Bean来配置
    /*
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        TenantFilter tenantFilter = new TenantFilter(); // 实例化
        // ... 其他配置 ...
        http.addFilterBefore(tenantFilter, UsernamePasswordAuthenticationFilter.class);
        // ...
        return http.build();
    }
    */

    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }

    // 配置UserDetailsService和PasswordEncoder
    // @Override
    // protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    //     auth.userDetailsService(userDetailsService).passwordEncoder(passwordEncoder);
    // }
}

通过http.addFilterBefore(tenantFilter, UsernamePasswordAuthenticationFilter.class)，我们明确指示Spring Security将tenantFilter放置在UsernamePasswordAuthenticationFilter之前。由于UsernamePasswordAuthenticationFilter是处理表单登录的核心过滤器之一，通常处于安全认证流程的早期，因此将TenantFilter放置在其之前，可以确保租户上下文在认证开始前就已经设置完毕。

最佳实践与注意事项

1. 优先使用Spring Security内置JWT支持： 除非有非常特殊的需求，否则强烈建议使用Spring Security内置的OAuth 2.0 Resource Server和JWT支持。它提供了开箱即用的JWT验证、签名验证、令牌解析等功能，并且与Spring Security的授权机制无缝集成，大大简化了开发并减少了潜在的安全漏洞。 配置示例（使用Spring Security内置JWT）：

   @Configuration
   @EnableWebSecurity
   public class SecurityConfig extends WebSecurityConfigurerAdapter {
       @Override
       protected void configure(HttpSecurity http) throws Exception {
           TenantFilter tenantFilter = new TenantFilter(); // 实例化
   
           http.csrf().disable()
               .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
               .and()
               .authorizeRequests()
                   .antMatchers("/api/public/**").permitAll() // 允许公共访问
                   .anyRequest().authenticated()
               .and()
               .addFilterBefore(tenantFilter, UsernamePasswordAuthenticationFilter.class) // 确保租户过滤器在认证前
               .oauth2ResourceServer().jwt(); // 启用JWT资源服务器
       }
   }

   对于更高级的JWT配置，例如自定义JWT解析器，可以参考Spring Security官方文档。

2. OncePerRequestFilter的重要性： 自定义过滤器应继承OncePerRequestFilter，以确保在每个请求的生命周期中只执行一次doFilterInternal方法，避免重复处理和资源浪费。

3. 租户上下文的清理： 在TenantFilter中，务必在finally块中清理租户上下文（例如ConnectionStorage.clear()），以防止内存泄漏或请求间的数据污染。

4. 异常处理： 在doFilterInternal方法中，确保对可能发生的异常进行适当处理，避免中断整个请求链。

总结

在Spring Security应用中，精确控制自定义过滤器的执行顺序是实现复杂业务逻辑（如多租户）的关键。通过@Order(Ordered.HIGHEST_PRECEDENCE)注解或更精确的http.addFilterBefore()方法，我们可以确保自定义的OncePerRequestFilter在Spring Security的核心认证和授权过滤器之前执行，从而为后续的安全处理提供正确的上下文。同时，强烈建议利用Spring Security内置的JWT支持，以提高安全性和开发效率。