当前位置：首页 > news >正文

Spring Security: 整体架构

news 2026/2/7 21:43:39

Filter

Spring Security 是基于 Sevlet Filter 实现的。下面是一次 Http 请求从 client 出发，与 Servlet 交互的图：

当客户端发送一个请求到应用，容器会创建一个 FilterChain，FilterChain 中包含多个 Filter 和 Servlet。这些 Filter 和 Servlet 是用来处理 HttpServletRequest 的。在 Spring MVC 应用中，Servlet 实际上是一个 DispatcherServlet。

DelegatingFilterProxy

Spring 提供了一个名字叫 DelegatingFilterProxy 的 Filter 实现。直译过来就是委托过滤器代理。DelegatingFilterProxy 可以对 Servlet 容器的生命周期和 Spring 的 ApplicationContext 容器进行桥接。Servlet 容器可以通过非 Spring 的方式注册 Filter 实例。也就是说我们可以通过 Servlet 容器机制注册 DelegatingFilterProxy，但是却可以把所有的工作委托给实现了 Filter 的 Spring Bean。

DelegatingFilterProxy 会从 ApplicationContext 容器中寻找并调用 Bean Filter0。DelegatingFilterProxy 允许推迟查找 Filter Bean 实例。这很重要，因为容器在启动前需要注册 Filter 实例。

FilterChainProxy

FilterChainProxy 由 DelegatingFilterProxy 包裹的一个 Filter 。FilterChainProxy 是一个通过 SecurityFilterChain 来包含多个 Filter 实例的特殊的 Filter。

SecurityFilterChain

SecurityFilterChain 被 FilterChainProxy 使用。SecurityFilterChain 用来确定当前请求应该调用哪些 Filter 实例。

在 SecurityFilterChain 中的 Security Filters 是典型的 Bean。但是它们是随着 FilterChainProxy 一起注册的，而不是跟着 DelegatingFilterProxy 一起注册的。FilterChainProxy 是 Spring Security 支持的起点。所以在排除认证会权限的问题时，可以将断点打在 FilterChainProxy 里。下图展示多个 SecurityFilterChain 实例：

在多 SecurityFilterChain 实例配置中，FilterChainProxy 决定哪个 SecurityFilterChain 将会被使用。只有第一个被匹配上的 SecurityFilterChain 才会被调用。比如一个请求 /api/a，它能与第0个 SecurityFilterChain /api/**和n个 /** 匹配，但是只会调用第0个。

每个 SecurityFilterChain 都有自己独立且隔离的 Filter 实例。

Security Filters

Security Filters 被通过 SecurityFilterChain 的 API 插入到 FilterChainProxy 中。这些 filter 可以被用作不同的目的。比如：认证、鉴权、漏洞保护等。这些 filter 以特定的顺序进行执行，从而保证它们在正确的时机被调用，比如认证需要在鉴权之前被执行。通常我们不需要关心这些 filter 的顺序，但是我们可以在 FilterOrderRegistration 类中查看这些顺序。

@Configuration  
@EnableWebSecurity  
public class SecurityConfig {  @Bean  
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {  http.csrf(Customizer.withDefaults())  .authorizeHttpRequests(authorize -> authorize  .anyRequest().authenticated())  .httpBasic(Customizer.withDefaults())  .formLogin(Customizer.withDefaults());  return http.build();  }  
}

上面的代码会导致 filter 的顺序如下：

Filter	Added by
CsrfFilter	`HttpSecurity#csrf`
UsernamePasswordAuthenticationFilter	`HttpSecurity#formLogin`
BasicAuthenticationFilter	`HttpSecurity#httpBasic`
AuthorizationFilter	`HttpSecurity#authorizeHttpRequests`

Printing the Security Filters

spring boot 在 info 级别的日志会打印请求要经过哪些 Spring Security 的 filter。在控制台中会打印成一行。与下面的日志看起来会有点不一样：

2023-06-14T08:55:22.321-03:00  INFO 76975 --- [           main] o.s.s.web.DefaultSecurityFilterChain     : Will secure any request with [
org.springframework.security.web.session.DisableEncodeUrlFilter@404db674,
org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter@50f097b5,
org.springframework.security.web.context.SecurityContextHolderFilter@6fc6deb7,
org.springframework.security.web.header.HeaderWriterFilter@6f76c2cc,
org.springframework.security.web.csrf.CsrfFilter@c29fe36,
org.springframework.security.web.authentication.logout.LogoutFilter@ef60710,
org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter@7c2dfa2,
org.springframework.security.web.authentication.ui.DefaultLoginPageGeneratingFilter@4397a639,
org.springframework.security.web.authentication.ui.DefaultLogoutPageGeneratingFilter@7add838c,
org.springframework.security.web.authentication.www.BasicAuthenticationFilter@5cc9d3d0,
org.springframework.security.web.savedrequest.RequestCacheAwareFilter@7da39774,
org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter@32b0876c,
org.springframework.security.web.authentication.AnonymousAuthenticationFilter@3662bdff,
org.springframework.security.web.access.ExceptionTranslationFilter@77681ce4,
org.springframework.security.web.access.intercept.AuthorizationFilter@169268a7]

如果我们想看到 filter 的调用链，以及 Spring Security 的详细报错信息，我们可以通过对日志级别的调整进行打印，将 org.springframework.security 的日志级别调整为：TRACE 即可。

logging:  level:  root: info  org.springframework.security: trace

发出一个 /hello 请求后，控制台输出如下：

2023-06-14T09:44:25.797-03:00 DEBUG 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Securing POST /hello
2023-06-14T09:44:25.797-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Invoking DisableEncodeUrlFilter (1/15)
2023-06-14T09:44:25.798-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Invoking WebAsyncManagerIntegrationFilter (2/15)
2023-06-14T09:44:25.800-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Invoking SecurityContextHolderFilter (3/15)
2023-06-14T09:44:25.801-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Invoking HeaderWriterFilter (4/15)
2023-06-14T09:44:25.802-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.security.web.FilterChainProxy        : Invoking CsrfFilter (5/15)
2023-06-14T09:44:25.814-03:00 DEBUG 76975 --- [nio-8080-exec-1] o.s.security.web.csrf.CsrfFilter         : Invalid CSRF token found for http://localhost:8080/hello
2023-06-14T09:44:25.814-03:00 DEBUG 76975 --- [nio-8080-exec-1] o.s.s.w.access.AccessDeniedHandlerImpl   : Responding with 403 status code
2023-06-14T09:44:25.814-03:00 TRACE 76975 --- [nio-8080-exec-1] o.s.s.w.header.writers.HstsHeaderWriter  : Not injecting HSTS header since it did not match request to [Is Secure]

添加自定义的 filter 到 Filter Chain

如果需要添加自定义的 filter，例如：添加一个校验 tenantId 的 filter：

首先定义一个 filter：

import java.io.IOException;import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;import org.springframework.security.access.AccessDeniedException;public class TenantFilter implements Filter {@Overridepublic void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {HttpServletRequest request = (HttpServletRequest) servletRequest;HttpServletResponse response = (HttpServletResponse) servletResponse;String tenantId = request.getHeader("X-Tenant-Id"); boolean hasAccess = isUserAllowed(tenantId); if (hasAccess) {filterChain.doFilter(request, response); return;}throw new AccessDeniedException("Access denied"); }
}

然后将自定义的 filter 加入到 security filter chain 中：

@Bean SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http // ... .addFilterBefore(new TenantFilter(), AuthorizationFilter.class); return http.build(); 
}

添加 filter 时，可以指定 filter 位于某个给定的 filter 的前或者后。从而保证 filter 的执行顺序。

需要注意的是，在定义 Filter 时，不要将 filter 定义为 Spring Bean。因为 Spring 会自动把它注册到 Spring 的容器中，从而导致 filter 被调用两次，一次被 Spring 容器调用，一次被 Spring Security 调用。

如果非要定义为 Spring Bean，可以使用 FilterRegistrationBean 来注册该filter，并把 enabled 属性设置为 false。示例代码如下:

@Bean
public FilterRegistrationBean<TenantFilter> tenantFilterRegistration(TenantFilter filter) {FilterRegistrationBean<TenantFilter> registration = new FilterRegistrationBean<>(filter);registration.setEnabled(false);return registration;
}

处理 Security Exceptions

ExceptionTranslationFilter 被作为一个 security filter 被插入到 FilterChainProxy 中，它可以将 AccessDeniedException 和 AuthenticationException 两个异常转换成 http response。

下图是 ExceptionTranslationFilter 与其他组件的关系：

如果应用没有抛出 AccessDeniedException 和 AuthenticationException 这两个异常，ExceptionTranslationFilter 什么都不会做。

在 Authentication 之间保存 Requests

在一个没有认证成功的请求过来后，有必要将 request 缓存起来，为认证成功后重新请求使用。

RequestCacheAwareFilter 类用 RequestCache 来保存 HttpServletRequest。默认情况下是使用 HttpSessionRequestCache ，下面的代码展示了如何自定义 RequestCache 实现，该实现用于检查 HttpSession 是否存在已保存的请求(如果存在名为 Continue 的参数)。

@Bean
DefaultSecurityFilterChain springSecurity(HttpSecurity http) throws Exception {HttpSessionRequestCache requestCache = new HttpSessionRequestCache();requestCache.setMatchingRequestParameterName("continue");http// ....requestCache((cache) -> cache.requestCache(requestCache));return http.build();
}

如果你想禁用 Request 缓存的话，可以使用 NullRequestCache 实现。示例代码如下：

@Bean
SecurityFilterChain springSecurity(HttpSecurity http) throws Exception {RequestCache nullRequestCache = new NullRequestCache();http// ....requestCache((cache) -> cache.requestCache(nullRequestCache));return http.build();
}