此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Security 6.4.3！spring-doc.cadn.net.cn

架构

本节讨论 Spring Security 在基于 Servlet 的应用程序中的高级体系结构。 我们在参考的 Authentication， Authorization， and Protection against Exploits 部分中建立了这种高级理解。spring-doc.cadn.net.cn

过滤器回顾

Spring Security 的 Servlet 支持基于 Servlet 过滤器，因此通常首先查看过滤器的角色会很有帮助。 下图显示了单个 HTTP 请求的处理程序的典型分层。spring-doc.cadn.net.cn

filterchain （筛选链）
图 1.FilterChain （筛选链）

客户端向应用程序发送请求，容器创建一个FilterChain，其中包含Filterinstances 和Servlet它应该处理HttpServletRequest，基于请求 URI 的路径。 在 Spring MVC 应用程序中，Servlet是DispatcherServlet. 最多一个Servlet可以处理单个HttpServletRequest和HttpServletResponse. 但是，不止一个Filter可用于：spring-doc.cadn.net.cn

  • 防止下游Filter实例或Servlet免于被调用。 在这种情况下，Filter通常会写入HttpServletResponse.spring-doc.cadn.net.cn

  • 修改HttpServletRequest或HttpServletResponse由下游使用Filter实例和Servlet.spring-doc.cadn.net.cn

的强大功能Filter来自FilterChain这被传递到它里面。spring-doc.cadn.net.cn

FilterChain使用示例
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
	// do something before the rest of the application
    chain.doFilter(request, response); // invoke the rest of the application
    // do something after the rest of the application
}
fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
    // do something before the rest of the application
    chain.doFilter(request, response) // invoke the rest of the application
    // do something after the rest of the application
}

由于Filter仅影响下游Filter实例和Servlet，则每个Filter非常重要。spring-doc.cadn.net.cn

委托过滤器代理

Spring 提供了一个Filter名为DelegatingFilterProxy这允许在 Servlet 容器的生命周期和 Spring 的生命周期之间架起桥梁ApplicationContext. Servlet 容器允许注册Filter实例，但它不知道 Spring 定义的 Bean。 您可以注册DelegatingFilterProxy通过标准的 Servlet 容器机制，但将所有工作委托给实现Filter.spring-doc.cadn.net.cn

这是一张如何作的图片DelegatingFilterProxy适合Filter实例和FilterChain.spring-doc.cadn.net.cn

DelegatingFilterProxy
图 2.委托过滤器代理

DelegatingFilterProxy查找Bean 过滤器0从ApplicationContext然后调用Bean 过滤器0. 下面的清单显示了DelegatingFilterProxy:spring-doc.cadn.net.cn

DelegatingFilterProxy伪代码
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
	Filter delegate = getFilterBean(someBeanName); (1)
	delegate.doFilter(request, response); (2)
}
fun doFilter(request: ServletRequest, response: ServletResponse, chain: FilterChain) {
	val delegate: Filter = getFilterBean(someBeanName) (1)
	delegate.doFilter(request, response) (2)
}
1 延迟获取已注册为 Spring Bean 的 Filter。 对于 DelegatingFilterProxy 中的示例 delegate是Bean 过滤器0.
2 将工作委托给 Spring Bean。

另一个好处DelegatingFilterProxy是它允许延迟查找Filterbean 实例。 这很重要，因为容器需要注册Filter实例。 但是， Spring 通常使用ContextLoaderListener来加载 Spring Bean，这只有在Filter需要注册实例。spring-doc.cadn.net.cn

FilterChainProxy

Spring Security 的 Servlet 支持包含在FilterChainProxy.FilterChainProxy是一种特殊的Filter由 Spring Security 提供，允许委托给多个Filter实例SecurityFilterChain. 因为FilterChainProxy是一个 Bean，它通常包装在 DelegatingFilterProxy 中。spring-doc.cadn.net.cn

下图显示了FilterChainProxy.spring-doc.cadn.net.cn

filterchainproxy
图 3.FilterChainProxy

SecurityFilterChain 安全过滤器链

SecurityFilterChain被 FilterChainProxy 用于确定哪个 Spring SecurityFilter应为当前请求调用实例。spring-doc.cadn.net.cn

下图显示了SecurityFilterChain.spring-doc.cadn.net.cn

SecurityFilterChain 安全过滤器链
图 4.SecurityFilterChain 安全过滤器链

安全过滤器SecurityFilterChain通常是 Bean，但它们是使用FilterChainProxy而不是 DelegatingFilterProxy。FilterChainProxy为直接向 Servlet 容器或 DelegatingFilterProxy 注册提供了许多优势。 首先，它为 Spring Security 的所有 Servlet 支持提供了一个起点。 因此，如果您尝试对 Spring Security 的 Servlet 支持进行故障排除，请在FilterChainProxy是一个很好的起点。spring-doc.cadn.net.cn

其次，由于FilterChainProxy是 Spring Security 使用的核心，它可以执行不被视为可选的任务。 例如，它会清除SecurityContext以避免内存泄漏。 它还应用 Spring Security 的HttpFirewall保护应用程序免受某些类型的攻击。spring-doc.cadn.net.cn

此外，它还在确定何时SecurityFilterChain应该调用。 在 Servlet 容器中，Filter实例仅基于 URL 调用。 然而FilterChainProxy可以根据HttpServletRequest通过使用RequestMatcher接口。spring-doc.cadn.net.cn

下图显示了多个SecurityFilterChain实例：spring-doc.cadn.net.cn

Multi SecurityFilterChain
图 5.多个 SecurityFilterChain

在多个 SecurityFilterChain 图中，FilterChainProxy决定哪个SecurityFilterChain应该使用。 只有第一个SecurityFilterChainthat matches 被调用。 如果 URL 为/api/messages/请求时，它首先匹配SecurityFilterChain0的模式/api/**，所以只有SecurityFilterChain0被调用，即使它也匹配SecurityFilterChainn. 如果 URL 为/messages/请求时，它与SecurityFilterChain0的模式/api/**所以FilterChainProxy继续尝试每个SecurityFilterChain. 假设没有其他SecurityFilterChaininstances match、SecurityFilterChainn被调用。spring-doc.cadn.net.cn

请注意，SecurityFilterChain0只有三个安全Filter已配置实例。 然而SecurityFilterChainn有四项安全保障Filter已配置实例。 需要注意的是，每个SecurityFilterChain可以是唯一的，并且可以单独配置。 实际上，SecurityFilterChain可能具有零安全性Filter实例（如果应用程序希望 Spring Security 忽略某些请求）。spring-doc.cadn.net.cn

安全过滤器

安全筛选器使用 SecurityFilterChain API 插入到 FilterChainProxy 中。 这些过滤器可用于多种不同的目的，例如身份验证、授权、漏洞利用保护等。 过滤器按特定顺序执行，以保证它们在正确的时间被调用，例如，Filter执行身份验证的Filter执行授权。 通常不需要知道 Spring Security 的Filters. 但是，有时了解顺序是有益的，如果您想了解它们，可以检查FilterOrderRegistration法典.spring-doc.cadn.net.cn

为了举例说明上述段落，让我们考虑以下安全配置：spring-doc.cadn.net.cn

@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();
    }

}
import org.springframework.security.config.web.servlet.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            csrf { }
            authorizeHttpRequests {
                authorize(anyRequest, authenticated)
            }
            httpBasic { }
            formLogin { }
        }
        return http.build()
    }

}

The above configuration will result in the following Filter ordering:spring-doc.cadn.net.cn

Filter Added by

CsrfFilterspring-doc.cadn.net.cn

HttpSecurity#csrfspring-doc.cadn.net.cn

UsernamePasswordAuthenticationFilterspring-doc.cadn.net.cn

HttpSecurity#formLoginspring-doc.cadn.net.cn

BasicAuthenticationFilterspring-doc.cadn.net.cn

HttpSecurity#httpBasicspring-doc.cadn.net.cn

AuthorizationFilterspring-doc.cadn.net.cn

HttpSecurity#authorizeHttpRequestsspring-doc.cadn.net.cn

  1. First, the CsrfFilter is invoked to protect against CSRF attacks.spring-doc.cadn.net.cn

  2. Second, the authentication filters are invoked to authenticate the request.spring-doc.cadn.net.cn

  3. Third, the AuthorizationFilter is invoked to authorize the request.spring-doc.cadn.net.cn

There might be other Filter instances that are not listed above. If you want to see the list of filters invoked for a particular request, you can print them.spring-doc.cadn.net.cn

Printing the Security Filters

Often times, it is useful to see the list of security Filters that are invoked for a particular request. For example, you want to make sure that the filter you have added is in the list of the security filters.spring-doc.cadn.net.cn

The list of filters is printed at INFO level on the application startup, so you can see something like the following on the console output for example:spring-doc.cadn.net.cn

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]

And that will give a pretty good idea of the security filters that are configured for each filter chain.spring-doc.cadn.net.cn

But that is not all, you can also configure your application to print the invocation of each individual filter for each request. That is helpful to see if the filter you have added is invoked for a particular request or to check where an exception is coming from. To do that, you can configure your application to log the security events.spring-doc.cadn.net.cn

Adding a Custom Filter to the Filter Chain

Mostly of the times, the default security filters are enough to provide security to your application. However, there might be times that you want to add a custom Filter to the security filter chain.spring-doc.cadn.net.cn

For example, let’s say that you want to add a Filter that gets a tenant id header and check if the current user has access to that tenant. The previous description already gives us a clue on where to add the filter, since we need to know the current user, we need to add it after the authentication filters.spring-doc.cadn.net.cn

First, let’s create the Filter:spring-doc.cadn.net.cn

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 {

    @Override
    public 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"); (1)
        boolean hasAccess = isUserAllowed(tenantId); (2)
        if (hasAccess) {
            filterChain.doFilter(request, response); (3)
            return;
        }
        throw new AccessDeniedException("Access denied"); (4)
    }

}

The sample code above does the following:spring-doc.cadn.net.cn

1 Get the tenant id from the request header.
2 Check if the current user has access to the tenant id.
3 If the user has access, then invoke the rest of the filters in the chain.
4 If the user does not have access, then throw an AccessDeniedException.

Instead of implementing Filter, you can extend from OncePerRequestFilter which is a base class for filters that are only invoked once per request and provides a doFilterInternal method with the HttpServletRequest and HttpServletResponse parameters.spring-doc.cadn.net.cn

Now, we need to add the filter to the security filter chain.spring-doc.cadn.net.cn

Java
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        // ...
        .addFilterBefore(new TenantFilter(), AuthorizationFilter.class); (1)
    return http.build();
}
Kotlin
@Bean
fun filterChain(http: HttpSecurity): SecurityFilterChain {
    http
        // ...
        .addFilterBefore(TenantFilter(), AuthorizationFilter::class.java) (1)
    return http.build()
}
1 Use HttpSecurity#addFilterBefore to add the TenantFilter before the AuthorizationFilter.

By adding the filter before the AuthorizationFilter we are making sure that the TenantFilter is invoked after the authentication filters. You can also use HttpSecurity#addFilterAfter to add the filter after a particular filter or HttpSecurity#addFilterAt to add the filter at a particular filter position in the filter chain.spring-doc.cadn.net.cn

And that’s it, now the TenantFilter will be invoked in the filter chain and will check if the current user has access to the tenant id.spring-doc.cadn.net.cn

Be careful when you declare your filter as a Spring bean, either by annotating it with @Component or by declaring it as a bean in your configuration, because Spring Boot will automatically register it with the embedded container. That may cause the filter to be invoked twice, once by the container and once by Spring Security and in a different order.spring-doc.cadn.net.cn

If you still want to declare your filter as a Spring bean to take advantage of dependency injection for example, and avoid the duplicate invocation, you can tell Spring Boot to not register it with the container by declaring a FilterRegistrationBean bean and setting its enabled property to false:spring-doc.cadn.net.cn

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

Handling Security Exceptions

The ExceptionTranslationFilter allows translation of AccessDeniedException and AuthenticationException into HTTP responses.spring-doc.cadn.net.cn

ExceptionTranslationFilter is inserted into the FilterChainProxy as one of the Security Filters.spring-doc.cadn.net.cn

The following image shows the relationship of ExceptionTranslationFilter to other components:spring-doc.cadn.net.cn

exceptiontranslationfilter

  • number 1 First, the ExceptionTranslationFilter invokes FilterChain.doFilter(request, response) to invoke the rest of the application.spring-doc.cadn.net.cn

  • number 2 If the user is not authenticated or it is an AuthenticationException, then Start Authentication.spring-doc.cadn.net.cn

  • number 3 Otherwise, if it is an AccessDeniedException, then Access Denied. The AccessDeniedHandler is invoked to handle access denied.spring-doc.cadn.net.cn

If the application does not throw an AccessDeniedException or an AuthenticationException, then ExceptionTranslationFilter does not do anything.spring-doc.cadn.net.cn

The pseudocode for ExceptionTranslationFilter looks something like this:spring-doc.cadn.net.cn

ExceptionTranslationFilter pseudocode
try {
	filterChain.doFilter(request, response); (1)
} catch (AccessDeniedException | AuthenticationException ex) {
	if (!authenticated || ex instanceof AuthenticationException) {
		startAuthentication(); (2)
	} else {
		accessDenied(); (3)
	}
}
1 As described in A Review of Filters, invoking FilterChain.doFilter(request, response) is the equivalent of invoking the rest of the application. This means that if another part of the application, (FilterSecurityInterceptor or method security) throws an AuthenticationException or AccessDeniedException it is caught and handled here.
2 If the user is not authenticated or it is an AuthenticationException, Start Authentication.
3 Otherwise, Access Denied

Saving Requests Between Authentication

As illustrated in Handling Security Exceptions, when a request has no authentication and is for a resource that requires authentication, there is a need to save the request for the authenticated resource to re-request after authentication is successful. In Spring Security this is done by saving the HttpServletRequest using a RequestCache implementation.spring-doc.cadn.net.cn

RequestCache

The HttpServletRequest is saved in the RequestCache. When the user successfully authenticates, the RequestCache is used to replay the original request. The RequestCacheAwareFilter uses the RequestCache to get the saved HttpServletRequest after the user authenticates, while the ExceptionTranslationFilter uses the RequestCache to save the HttpServletRequest after it detects AuthenticationException, before redirecting the user to the login endpoint.spring-doc.cadn.net.cn

By default, an HttpSessionRequestCache is used. The code below demonstrates how to customize the RequestCache implementation that is used to check the HttpSession for a saved request if the parameter named continue is present.spring-doc.cadn.net.cn

RequestCache Only Checks for Saved Requests if continue Parameter Present
@Bean
DefaultSecurityFilterChain springSecurity(HttpSecurity http) throws Exception {
	HttpSessionRequestCache requestCache = new HttpSessionRequestCache();
	requestCache.setMatchingRequestParameterName("continue");
	http
		// ...
		.requestCache((cache) -> cache
			.requestCache(requestCache)
		);
	return http.build();
}
@Bean
open fun springSecurity(http: HttpSecurity): SecurityFilterChain {
    val httpRequestCache = HttpSessionRequestCache()
    httpRequestCache.setMatchingRequestParameterName("continue")
    http {
        requestCache {
            requestCache = httpRequestCache
        }
    }
    return http.build()
}
<http auto-config="true">
	<!-- ... -->
	<request-cache ref="requestCache"/>
</http>

<b:bean id="requestCache" class="org.springframework.security.web.savedrequest.HttpSessionRequestCache"
	p:matchingRequestParameterName="continue"/>

Prevent the Request From Being Saved

There are a number of reasons you may want to not store the user’s unauthenticated request in the session. You may want to offload that storage onto the user’s browser or store it in a database. Or you may want to shut off this feature since you always want to redirect the user to the home page instead of the page they tried to visit before login.spring-doc.cadn.net.cn

To do that, you can use the NullRequestCache implementation.spring-doc.cadn.net.cn

Prevent the Request From Being Saved
@Bean
SecurityFilterChain springSecurity(HttpSecurity http) throws Exception {
    RequestCache nullRequestCache = new NullRequestCache();
    http
        // ...
        .requestCache((cache) -> cache
            .requestCache(nullRequestCache)
        );
    return http.build();
}
@Bean
open fun springSecurity(http: HttpSecurity): SecurityFilterChain {
    val nullRequestCache = NullRequestCache()
    http {
        requestCache {
            requestCache = nullRequestCache
        }
    }
    return http.build()
}
<http auto-config="true">
	<!-- ... -->
	<request-cache ref="nullRequestCache"/>
</http>

<b:bean id="nullRequestCache" class="org.springframework.security.web.savedrequest.NullRequestCache"/>

RequestCacheAwareFilter

The RequestCacheAwareFilter uses the RequestCache to replay the original request.spring-doc.cadn.net.cn

Logging

Spring Security provides comprehensive logging of all security related events at the DEBUG and TRACE level. This can be very useful when debugging your application because for security measures Spring Security does not add any detail of why a request has been rejected to the response body. If you come across a 401 or 403 error, it is very likely that you will find a log message that will help you understand what is going on.spring-doc.cadn.net.cn

Let’s consider an example where a user tries to make a POST request to a resource that has CSRF protection enabled without the CSRF token. With no logs, the user will see a 403 error with no explanation of why the request was rejected. However, if you enable logging for Spring Security, you will see a log message like this:spring-doc.cadn.net.cn

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]

It becomes clear that the CSRF token is missing and that is why the request is being denied.spring-doc.cadn.net.cn

To configure your application to log all the security events, you can add the following to your application:spring-doc.cadn.net.cn

application.properties in Spring Boot
logging.level.org.springframework.security=TRACE
logback.xml
<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <!-- ... -->
    </appender>
    <!-- ... -->
    <logger name="org.springframework.security" level="trace" additivity="false">
        <appender-ref ref="Console" />
    </logger>
</configuration>