跨站请求伪造 (CSRF)

在允许最终用户登录的应用程序中，务必考虑如何防范跨站请求伪造 (CSRF)。

对于不安全的 HTTP 方法（例如 POST 请求），Spring Security 默认情况下会防止 CSRF 攻击，因此无需编写任何额外代码。您可以使用以下方法显式指定默认配置

配置 CSRF 保护

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf(Customizer.withDefaults());
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf { }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf/>
</http>

要了解有关应用程序 CSRF 保护的更多信息，请考虑以下用例

了解 CSRF 保护的组件

CSRF 保护由几个组件提供，这些组件构成在CsrfFilter中。

csrf
图 1. CsrfFilter 组件

CSRF 保护分为两部分

  1. 通过委托给CsrfTokenRequestHandler使应用程序可以使用CsrfToken。

  2. 确定请求是否需要 CSRF 保护，加载并验证令牌，以及处理AccessDeniedException。

csrf processing
图 2. CsrfFilter 处理过程

  • 数字 1 首先，加载DeferredCsrfToken，它保存对CsrfTokenRepository的引用，以便稍后（在数字 4中）加载持久化的CsrfToken。

  • 数字 2 其次，将Supplier<CsrfToken>（由DeferredCsrfToken创建）提供给CsrfTokenRequestHandler，它负责填充请求属性，以便使应用程序的其余部分可以使用CsrfToken。

  • 数字 3接下来，开始主要的 CSRF 保护处理，并检查当前请求是否需要 CSRF 保护。如果不需要，则继续过滤器链并结束处理。

  • 数字 4如果需要 CSRF 保护，则最终从DeferredCsrfToken加载持久化的CsrfToken。

  • number 5 接下来，将使用 CsrfTokenRequestHandler 解析客户端提供的实际 CSRF 令牌（如有）。

  • number 6 将实际的 CSRF 令牌与持久化的 CsrfToken 进行比较。如果有效，则继续过滤器链，处理结束。

  • number 7 如果实际的 CSRF 令牌无效（或缺失），则将 AccessDeniedException 传递给 AccessDeniedHandler，处理结束。

迁移到 Spring Security 6

从 Spring Security 5 迁移到 6 时，有一些更改可能会影响您的应用程序。以下是 Spring Security 6 中 CSRF 保护方面更改的概述

Spring Security 6 中的更改需要对单页应用程序进行额外的配置，因此您可能会发现 单页应用程序 部分特别有用。

有关将 Spring Security 5 应用程序迁移的更多信息，请参阅 漏洞防护 部分的 迁移 章节。

持久化 CsrfToken

CsrfToken 使用 CsrfTokenRepository 持久化。

默认情况下，使用 HttpSessionCsrfTokenRepository 将令牌存储在会话中。Spring Security 还提供 CookieCsrfTokenRepository 用于将令牌存储在 Cookie 中。您还可以指定 您自己的实现 来将令牌存储在您喜欢的任何位置。

使用 HttpSessionCsrfTokenRepository

默认情况下，Spring Security 使用 HttpSessionCsrfTokenRepository 将预期的 CSRF 令牌存储在 HttpSession 中，因此无需任何额外代码。

HttpSessionCsrfTokenRepository 从会话（无论是在内存中、缓存中还是数据库中）读取令牌。如果您需要直接访问会话属性，请首先使用 HttpSessionCsrfTokenRepository#setSessionAttributeName 配置会话属性名称。

您可以使用以下配置显式指定默认配置

配置 HttpSessionCsrfTokenRepository

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRepository(new HttpSessionCsrfTokenRepository())
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRepository = HttpSessionCsrfTokenRepository()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf token-repository-ref="tokenRepository"/>
</http>
<b:bean id="tokenRepository"
	class="org.springframework.security.web.csrf.HttpSessionCsrfTokenRepository"/>

您可以将 CsrfToken 持久化到 Cookie 中，以 支持基于 JavaScript 的应用程序，方法是使用 CookieCsrfTokenRepository。

CookieCsrfTokenRepository 默认写入名为 XSRF-TOKEN 的 Cookie，并从名为 X-XSRF-TOKEN 的 HTTP 请求头或名为 _csrf 的请求参数中读取它。这些默认值来自 Angular 及其前身 AngularJS。

有关此主题的更多最新信息，请参阅 跨站点请求伪造 (XSRF) 保护 指南和 HttpClientXsrfModule。

您可以使用以下配置配置 CookieCsrfTokenRepository

此示例显式地将 HttpOnly 设置为 false。这是必要的，可以让 JavaScript 框架（例如 Angular）读取它。如果您不需要直接使用 JavaScript 读取 Cookie，我们建议省略 HttpOnly（使用 new CookieCsrfTokenRepository() 代替），以提高安全性。

自定义 CsrfTokenRepository

在某些情况下，您可能需要实现自定义的 CsrfTokenRepository。

实现 CsrfTokenRepository 接口后，您可以使用以下配置将 Spring Security 配置为使用它

配置自定义 CsrfTokenRepository

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRepository(new CustomCsrfTokenRepository())
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRepository = CustomCsrfTokenRepository()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf token-repository-ref="tokenRepository"/>
</http>
<b:bean id="tokenRepository"
	class="example.CustomCsrfTokenRepository"/>

处理 CsrfToken

CsrfToken 使用 CsrfTokenRequestHandler 提供给应用程序。此组件还负责从 HTTP 标头或请求参数中解析 CsrfToken。

默认情况下，使用 XorCsrfTokenRequestAttributeHandler 来提供对 CsrfToken 的 BREACH 保护。Spring Security 还提供 CsrfTokenRequestAttributeHandler 用于选择退出 BREACH 保护。您还可以指定 您自己的实现 来自定义处理和解析令牌的策略。

使用 XorCsrfTokenRequestAttributeHandler (BREACH)

XorCsrfTokenRequestAttributeHandler 将 CsrfToken 作为名为 _csrf 的 HttpServletRequest 属性提供，并另外提供对 BREACH 的保护。

CsrfToken 也作为请求属性提供，使用名称 CsrfToken.class.getName()。此名称不可配置，但可以使用 XorCsrfTokenRequestAttributeHandler#setCsrfRequestAttributeName 更改名称 _csrf。

此实现还从请求中解析令牌值，作为请求标头（默认为 X-CSRF-TOKEN 或 X-XSRF-TOKEN 之一）或请求参数（默认为 _csrf）。

BREACH 保护是通过将随机性编码到 CSRF 令牌值中来提供的，以确保返回的 CsrfToken 在每次请求时都会更改。稍后将令牌解析为标头值或请求参数时，它将被解码以获取原始令牌，然后将其与 持久化的 CsrfToken 进行比较。

Spring Security 默认情况下会保护 CSRF 令牌免受 BREACH 攻击，因此无需任何额外代码。您可以使用以下配置显式指定默认配置

配置 BREACH 保护

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRequestHandler(new XorCsrfTokenRequestAttributeHandler())
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRequestHandler = XorCsrfTokenRequestAttributeHandler()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf request-handler-ref="requestHandler"/>
</http>
<b:bean id="requestHandler"
	class="org.springframework.security.web.csrf.XorCsrfTokenRequestAttributeHandler"/>

使用 CsrfTokenRequestAttributeHandler

CsrfTokenRequestAttributeHandler 将 CsrfToken 作为名为 _csrf 的 HttpServletRequest 属性提供。

CsrfToken 也作为请求属性提供，使用名称 CsrfToken.class.getName()。此名称不可配置，但可以使用 CsrfTokenRequestAttributeHandler#setCsrfRequestAttributeName 更改名称 _csrf。

此实现还从请求中解析令牌值，作为请求标头（默认为 X-CSRF-TOKEN 或 X-XSRF-TOKEN 之一）或请求参数（默认为 _csrf）。

CsrfTokenRequestAttributeHandler 的主要用途是选择退出 CsrfToken 的 BREACH 保护，这可以使用以下配置进行配置

选择退出 BREACH 保护

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRequestHandler = CsrfTokenRequestAttributeHandler()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf request-handler-ref="requestHandler"/>
</http>
<b:bean id="requestHandler"
	class="org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler"/>

自定义 CsrfTokenRequestHandler

您可以实现 CsrfTokenRequestHandler 接口来自定义处理和解析令牌的策略。

CsrfTokenRequestHandler 接口是一个 @FunctionalInterface，可以使用 lambda 表达式来实现，以自定义请求处理。您需要实现完整的接口才能自定义如何从请求中解析令牌。有关使用委托来实现处理和解析令牌的自定义策略的示例，请参阅 为单页应用程序配置 CSRF。

实现 CsrfTokenRequestHandler 接口后，您可以使用以下配置将 Spring Security 配置为使用它

配置自定义 CsrfTokenRequestHandler

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRequestHandler(new CustomCsrfTokenRequestHandler())
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRequestHandler = CustomCsrfTokenRequestHandler()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf request-handler-ref="requestHandler"/>
</http>
<b:bean id="requestHandler"
	class="example.CustomCsrfTokenRequestHandler"/>

CsrfToken 的延迟加载

默认情况下，Spring Security 会延迟加载 CsrfToken，直到需要它为止。

每当使用 不安全的 HTTP 方法（例如 POST）进行请求时，都需要 CsrfToken。此外，任何将令牌呈现给响应的请求都需要它，例如包含用于 CSRF 令牌的隐藏 <input> 的带有 <form> 标签的网页。

因为 Spring Security 默认情况下也将 CsrfToken 存储在 HttpSession 中，所以延迟的 CSRF 令牌可以通过不再需要在每次请求时加载会话来提高性能。

如果您想选择退出延迟令牌并导致在每次请求时加载 CsrfToken，您可以使用以下配置来实现

选择退出延迟 CSRF 令牌

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		XorCsrfTokenRequestAttributeHandler requestHandler = new XorCsrfTokenRequestAttributeHandler();
		// set the name of the attribute the CsrfToken will be populated on
		requestHandler.setCsrfRequestAttributeName(null);
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRequestHandler(requestHandler)
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        val requestHandler = XorCsrfTokenRequestAttributeHandler()
        // set the name of the attribute the CsrfToken will be populated on
        requestHandler.setCsrfRequestAttributeName(null)
        http {
            // ...
            csrf {
                csrfTokenRequestHandler = requestHandler
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf request-handler-ref="requestHandler"/>
</http>
<b:bean id="requestHandler"
	class="org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler">
	<b:property name="csrfRequestAttributeName">
		<b:null/>
	</b:property>
</b:bean>

通过将 csrfRequestAttributeName 设置为 null，必须首先加载 CsrfToken 以确定要使用的属性名称。这会导致在每次请求时加载 CsrfToken。

与 CSRF 保护集成

对于 同步器令牌模式 以防止 CSRF 攻击，我们必须在 HTTP 请求中包含实际的 CSRF 令牌。这必须包含在请求的一部分（表单参数、HTTP 标头或其他部分）中，浏览器不会自动将其包含在 HTTP 请求中。

以下部分描述了前端或客户端应用程序与受 CSRF 保护的后端应用程序集成的各种方法

HTML 表单

要提交 HTML 表单，必须将 CSRF 令牌作为隐藏输入包含在表单中。例如，呈现的 HTML 可能如下所示

HTML 表单中的 CSRF 令牌
<input type="hidden"
	name="_csrf"
	value="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>

以下视图技术会自动将实际的 CSRF 令牌包含在具有不安全 HTTP 方法（例如 POST）的表单中

如果这些选项不可用，您可以利用以下事实：CsrfToken 作为名为_csrf 的HttpServletRequest 属性公开。以下示例使用 JSP 来实现这一点。

使用请求属性在 HTML 表单中包含 CSRF 令牌
<c:url var="logoutUrl" value="/logout"/>
<form action="${logoutUrl}"
	method="post">
<input type="submit"
	value="Log out" />
<input type="hidden"
	name="${_csrf.parameterName}"
	value="${_csrf.token}"/>
</form>

JavaScript 应用

JavaScript 应用通常使用 JSON 而不是 HTML。如果使用 JSON，您可以将 CSRF 令牌提交到 HTTP 请求头中，而不是请求参数。

为了获取 CSRF 令牌，您可以配置 Spring Security 将预期的 CSRF 令牌存储在 Cookie 中。通过将预期令牌存储在 Cookie 中，像Angular 这样的 JavaScript 框架可以自动将实际的 CSRF 令牌作为 HTTP 请求头包含。

将单页应用 (SPA) 与 Spring Security 的 CSRF 保护集成时，需要特别考虑 BREACH 保护和延迟令牌。完整的配置示例在下一节中提供。

您可以在以下章节中阅读不同类型的 JavaScript 应用的信息

单页应用

将单页应用 (SPA) 与 Spring Security 的 CSRF 保护集成时，需要特别考虑。

回想一下，Spring Security 默认情况下提供CsrfToken 的 BREACH 保护。当将预期的 CSRF 令牌存储在 Cookie 中时，JavaScript 应用只能访问纯令牌值，而_不会_访问编码值。需要提供一个自定义请求处理程序来解析实际的令牌值。

此外，存储 CSRF 令牌的 Cookie 将在身份验证成功和注销成功后被清除。Spring Security 默认情况下会延迟加载新的 CSRF 令牌，需要额外的工作才能返回新的 Cookie。

身份验证成功和注销成功后需要刷新令牌，因为CsrfAuthenticationStrategy 和 CsrfLogoutHandler 将清除之前的令牌。客户端应用将无法执行不安全的 HTTP 请求（例如 POST 请求），除非获取新的令牌。

为了轻松地将单页应用与 Spring Security 集成，可以使用以下配置

为单页应用配置 CSRF

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())   (1)
				.csrfTokenRequestHandler(new SpaCsrfTokenRequestHandler())            (2)
			)
			.addFilterAfter(new CsrfCookieFilter(), BasicAuthenticationFilter.class); (3)
		return http.build();
	}
}

final class SpaCsrfTokenRequestHandler extends CsrfTokenRequestAttributeHandler {
	private final CsrfTokenRequestHandler delegate = new XorCsrfTokenRequestAttributeHandler();

	@Override
	public void handle(HttpServletRequest request, HttpServletResponse response, Supplier<CsrfToken> csrfToken) {
		/*
		 * Always use XorCsrfTokenRequestAttributeHandler to provide BREACH protection of
		 * the CsrfToken when it is rendered in the response body.
		 */
		this.delegate.handle(request, response, csrfToken);
	}

	@Override
	public String resolveCsrfTokenValue(HttpServletRequest request, CsrfToken csrfToken) {
		/*
		 * If the request contains a request header, use CsrfTokenRequestAttributeHandler
		 * to resolve the CsrfToken. This applies when a single-page application includes
		 * the header value automatically, which was obtained via a cookie containing the
		 * raw CsrfToken.
		 */
		if (StringUtils.hasText(request.getHeader(csrfToken.getHeaderName()))) {
			return super.resolveCsrfTokenValue(request, csrfToken);
		}
		/*
		 * In all other cases (e.g. if the request contains a request parameter), use
		 * XorCsrfTokenRequestAttributeHandler to resolve the CsrfToken. This applies
		 * when a server-side rendered form includes the _csrf request parameter as a
		 * hidden input.
		 */
		return this.delegate.resolveCsrfTokenValue(request, csrfToken);
	}
}

final class CsrfCookieFilter extends OncePerRequestFilter {

	@Override
	protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
			throws ServletException, IOException {
		CsrfToken csrfToken = (CsrfToken) request.getAttribute("_csrf");
		// Render the token value to a cookie by causing the deferred token to be loaded
		csrfToken.getToken();

		filterChain.doFilter(request, response);
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                csrfTokenRepository = CookieCsrfTokenRepository.withHttpOnlyFalse()    (1)
                csrfTokenRequestHandler = SpaCsrfTokenRequestHandler()                 (2)
            }
        }
        http.addFilterAfter(CsrfCookieFilter(), BasicAuthenticationFilter::class.java) (3)
        return http.build()
    }
}

class SpaCsrfTokenRequestHandler : CsrfTokenRequestAttributeHandler() {
    private val delegate: CsrfTokenRequestHandler = XorCsrfTokenRequestAttributeHandler()

    override fun handle(request: HttpServletRequest, response: HttpServletResponse, csrfToken: Supplier<CsrfToken>) {
        /*
         * Always use XorCsrfTokenRequestAttributeHandler to provide BREACH protection of
         * the CsrfToken when it is rendered in the response body.
         */
        delegate.handle(request, response, csrfToken)
    }

    override fun resolveCsrfTokenValue(request: HttpServletRequest, csrfToken: CsrfToken): String? {
        /*
         * If the request contains a request header, use CsrfTokenRequestAttributeHandler
         * to resolve the CsrfToken. This applies when a single-page application includes
         * the header value automatically, which was obtained via a cookie containing the
         * raw CsrfToken.
         */
        return if (StringUtils.hasText(request.getHeader(csrfToken.headerName))) {
            super.resolveCsrfTokenValue(request, csrfToken)
        } else {
            /*
             * In all other cases (e.g. if the request contains a request parameter), use
             * XorCsrfTokenRequestAttributeHandler to resolve the CsrfToken. This applies
             * when a server-side rendered form includes the _csrf request parameter as a
             * hidden input.
             */
            delegate.resolveCsrfTokenValue(request, csrfToken)
        }
    }
}

class CsrfCookieFilter : OncePerRequestFilter() {

    @Throws(ServletException::class, IOException::class)
    override fun doFilterInternal(request: HttpServletRequest, response: HttpServletResponse, filterChain: FilterChain) {
        val csrfToken = request.getAttribute("_csrf") as CsrfToken
        // Render the token value to a cookie by causing the deferred token to be loaded
        csrfToken.token
        filterChain.doFilter(request, response)
    }
}
<http>
	<!-- ... -->
	<csrf
		token-repository-ref="tokenRepository"                        (1)
		request-handler-ref="requestHandler"/>                        (2)
	<custom-filter ref="csrfCookieFilter" after="BASIC_AUTH_FILTER"/> (3)
</http>
<b:bean id="tokenRepository"
	class="org.springframework.security.web.csrf.CookieCsrfTokenRepository"
	p:cookieHttpOnly="false"/>
<b:bean id="requestHandler"
	class="example.SpaCsrfTokenRequestHandler"/>
<b:bean id="csrfCookieFilter"
	class="example.CsrfCookieFilter"/>
1 将 CookieCsrfTokenRepository 的 HttpOnly 设置为 false，以便 JavaScript 应用可以读取 Cookie。
2 配置一个自定义 CsrfTokenRequestHandler，该处理程序根据是 HTTP 请求头 (X-XSRF-TOKEN) 还是请求参数 (_csrf) 来解析 CSRF 令牌。
3 配置一个自定义 Filter 以在每次请求时加载 CsrfToken，这将在需要时返回一个新的 Cookie。

多页应用

对于在每个页面上加载 JavaScript 的多页应用，除了将 CSRF 令牌存储在 Cookie 中之外，还可以将 CSRF 令牌包含在您的 meta 标记中。HTML 可能如下所示

在 HTML meta 标记中包含 CSRF 令牌
<html>
<head>
	<meta name="_csrf" content="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
	<meta name="_csrf_header" content="X-CSRF-TOKEN"/>
	<!-- ... -->
</head>
<!-- ... -->
</html>

为了在请求中包含 CSRF 令牌，您可以利用以下事实：CsrfToken 作为名为_csrf 的HttpServletRequest 属性公开。以下示例使用 JSP 来实现这一点。

使用请求属性在 HTML meta 标记中包含 CSRF 令牌
<html>
<head>
	<meta name="_csrf" content="${_csrf.token}"/>
	<!-- default header name is X-CSRF-TOKEN -->
	<meta name="_csrf_header" content="${_csrf.headerName}"/>
	<!-- ... -->
</head>
<!-- ... -->
</html>

一旦 meta 标记包含 CSRF 令牌，JavaScript 代码就可以读取 meta 标记并将 CSRF 令牌作为标头包含。如果您使用 jQuery，可以使用以下代码：

在 AJAX 请求中包含 CSRF 令牌
$(function () {
	var token = $("meta[name='_csrf']").attr("content");
	var header = $("meta[name='_csrf_header']").attr("content");
	$(document).ajaxSend(function(e, xhr, options) {
		xhr.setRequestHeader(header, token);
	});
});

其他 JavaScript 应用

JavaScript 应用的另一个选项是将 CSRF 令牌包含在 HTTP 响应头中。

实现此目的的一种方法是使用带有CsrfTokenArgumentResolver 的@ControllerAdvice。以下是应用于应用中所有控制器端点的@ControllerAdvice 示例：

在 HTTP 响应头中包含 CSRF 令牌

  • Java

  • Kotlin

@ControllerAdvice
public class CsrfControllerAdvice {

	@ModelAttribute
	public void getCsrfToken(HttpServletResponse response, CsrfToken csrfToken) {
		response.setHeader(csrfToken.getHeaderName(), csrfToken.getToken());
	}

}
@ControllerAdvice
class CsrfControllerAdvice {

	@ModelAttribute
	fun getCsrfToken(response: HttpServletResponse, csrfToken: CsrfToken) {
		response.setHeader(csrfToken.headerName, csrfToken.token)
	}

}

因为此 @ControllerAdvice 应用于应用中的所有端点，所以它会导致在每次请求时加载 CSRF 令牌，这可能会抵消使用HttpSessionCsrfTokenRepository 时延迟令牌 的好处。但是，使用CookieCsrfTokenRepository 时，这通常不是问题。

务必记住，控制器端点和控制器建议是在 Spring Security 过滤器链_之后_调用的。这意味着只有当请求通过过滤器链传递到您的应用时，才会应用此 @ControllerAdvice。有关在过滤器链中添加过滤器以更早访问HttpServletResponse 的示例，请参见单页应用的配置。

现在，对于控制器建议应用的任何自定义端点，CSRF 令牌都将在响应头中可用（默认情况下为X-CSRF-TOKEN 或X-XSRF-TOKEN）。可以使用任何对后端的请求从响应中获取令牌，后续请求可以使用相同名称的请求头包含令牌。

移动应用

与JavaScript 应用一样，移动应用通常使用 JSON 而不是 HTML。_不_提供浏览器流量的后端应用可以选择禁用 CSRF。在这种情况下，无需额外的工作。

但是，也提供浏览器流量并因此_仍然需要_CSRF 保护的后端应用可能会继续将CsrfToken存储在会话中，而不是存储在 Cookie 中。

在这种情况下，与后端集成的典型模式是公开一个/csrf 端点，允许前端（移动或浏览器客户端）根据需要请求 CSRF 令牌。使用此模式的好处是 CSRF 令牌可以继续延迟，并且只需要在请求需要 CSRF 保护时才从会话中加载。使用自定义端点也意味着客户端应用可以通过发出显式请求来请求按需生成新令牌（如有必要）。

此模式可用于需要 CSRF 保护的任何类型的应用，而不仅仅是移动应用。虽然在这些情况下通常不需要这种方法，但它是与 CSRF 保护的后端集成的另一种选择。

以下是使用CsrfTokenArgumentResolver 的/csrf 端点示例：

/csrf 端点

  • Java

  • Kotlin

@RestController
public class CsrfController {

    @GetMapping("/csrf")
    public CsrfToken csrf(CsrfToken csrfToken) {
        return csrfToken;
    }

}
@RestController
class CsrfController {

    @GetMapping("/csrf")
    fun csrf(csrfToken: CsrfToken): CsrfToken {
        return csrfToken
    }

}

如果在使用服务器进行身份验证之前需要上述端点，您可以考虑添加.requestMatchers("/csrf").permitAll()。

应用启动或初始化（例如，在加载时）以及身份验证成功和注销成功后，都应调用此端点以获取 CSRF 令牌。

身份验证成功和注销成功后需要刷新令牌，因为CsrfAuthenticationStrategy 和 CsrfLogoutHandler 将清除之前的令牌。客户端应用将无法执行不安全的 HTTP 请求（例如 POST 请求），除非获取新的令牌。

获得 CSRF 令牌后，您需要将其作为 HTTP 请求头（默认为X-CSRF-TOKEN 或X-XSRF-TOKEN 之一）自己包含。

处理AccessDeniedException

要处理AccessDeniedException（例如InvalidCsrfTokenException），您可以配置 Spring Security 以任何您喜欢的方式处理这些异常。例如，您可以使用以下配置来配置自定义拒绝访问页面：

配置AccessDeniedHandler

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.exceptionHandling((exceptionHandling) -> exceptionHandling
				.accessDeniedPage("/access-denied")
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            exceptionHandling {
                accessDeniedPage = "/access-denied"
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<access-denied-handler error-page="/access-denied"/>
</http>

CSRF 测试

您可以使用 Spring Security 的测试支持和CsrfRequestPostProcessor 来测试 CSRF 保护，如下所示：

测试 CSRF 保护

  • Java

  • Kotlin

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*;
import static org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@ExtendWith(SpringExtension.class)
@ContextConfiguration(classes = SecurityConfig.class)
@WebAppConfiguration
public class CsrfTests {

	private MockMvc mockMvc;

	@BeforeEach
	public void setUp(WebApplicationContext applicationContext) {
		this.mockMvc = MockMvcBuilders.webAppContextSetup(applicationContext)
			.apply(springSecurity())
			.build();
	}

	@Test
	public void loginWhenValidCsrfTokenThenSuccess() throws Exception {
		this.mockMvc.perform(post("/login").with(csrf())
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().is3xxRedirection())
			.andExpect(header().string(HttpHeaders.LOCATION, "/"));
	}

	@Test
	public void loginWhenInvalidCsrfTokenThenForbidden() throws Exception {
		this.mockMvc.perform(post("/login").with(csrf().useInvalidToken())
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().isForbidden());
	}

	@Test
	public void loginWhenMissingCsrfTokenThenForbidden() throws Exception {
		this.mockMvc.perform(post("/login")
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().isForbidden());
	}

	@Test
	@WithMockUser
	public void logoutWhenValidCsrfTokenThenSuccess() throws Exception {
		this.mockMvc.perform(post("/logout").with(csrf())
				.accept(MediaType.TEXT_HTML))
			.andExpect(status().is3xxRedirection())
			.andExpect(header().string(HttpHeaders.LOCATION, "/login?logout"));
	}
}
import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*
import org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.*
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.*

@ExtendWith(SpringExtension::class)
@ContextConfiguration(classes = [SecurityConfig::class])
@WebAppConfiguration
class CsrfTests {
	private lateinit var mockMvc: MockMvc

	@BeforeEach
	fun setUp(applicationContext: WebApplicationContext) {
		mockMvc = MockMvcBuilders.webAppContextSetup(applicationContext)
			.apply<DefaultMockMvcBuilder>(springSecurity())
			.build()
	}

	@Test
	fun loginWhenValidCsrfTokenThenSuccess() {
		mockMvc.perform(post("/login").with(csrf())
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().is3xxRedirection)
			.andExpect(header().string(HttpHeaders.LOCATION, "/"))
	}

	@Test
	fun loginWhenInvalidCsrfTokenThenForbidden() {
		mockMvc.perform(post("/login").with(csrf().useInvalidToken())
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().isForbidden)
	}

	@Test
	fun loginWhenMissingCsrfTokenThenForbidden() {
		mockMvc.perform(post("/login")
				.accept(MediaType.TEXT_HTML)
				.param("username", "user")
				.param("password", "password"))
			.andExpect(status().isForbidden)
	}

	@Test
	@WithMockUser
	@Throws(Exception::class)
	fun logoutWhenValidCsrfTokenThenSuccess() {
		mockMvc.perform(post("/logout").with(csrf())
				.accept(MediaType.TEXT_HTML))
			.andExpect(status().is3xxRedirection)
			.andExpect(header().string(HttpHeaders.LOCATION, "/login?logout"))
	}
}

禁用 CSRF 保护

默认情况下，CSRF 保护已启用，这会影响与后端集成和测试您的应用。在禁用 CSRF 保护之前，请考虑它是否适合您的应用。

您还可以考虑哪些端点不需要 CSRF 保护，并配置忽略规则，如下例所示：

忽略请求

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .csrf((csrf) -> csrf
                .ignoringRequestMatchers("/api/*")
            );
        return http.build();
    }
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                ignoringRequestMatchers("/api/*")
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf request-matcher-ref="csrfMatcher"/>
</http>
<b:bean id="csrfMatcher"
    class="org.springframework.security.web.util.matcher.AndRequestMatcher">
    <b:constructor-arg value="#{T(org.springframework.security.web.csrf.CsrfFilter).DEFAULT_CSRF_MATCHER}"/>
    <b:constructor-arg>
        <b:bean class="org.springframework.security.web.util.matcher.NegatedRequestMatcher">
            <b:bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher">
                <b:constructor-arg value="/api/*"/>
            </b:bean>
        </b:bean>
    </b:constructor-arg>
</b:bean>

如果需要禁用 CSRF 保护，可以使用以下配置：

禁用 CSRF

  • Java

  • Kotlin

  • XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf.disable());
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            csrf {
                disable()
            }
        }
        return http.build()
    }
}
<http>
	<!-- ... -->
	<csrf disabled="true"/>
</http>

CSRF 注意事项

在实现针对 CSRF 攻击的保护时，有一些特殊的注意事项。本节讨论这些注意事项与 servlet 环境相关的内容。有关更一般的讨论，请参见CSRF 注意事项。

登录

务必为登录请求要求 CSRF，以防止伪造登录尝试。Spring Security 的 servlet 支持开箱即用地实现了这一点。

注销

务必为注销请求要求 CSRF，以防止伪造注销尝试。如果启用了 CSRF 保护（默认值），Spring Security 的LogoutFilter 将只处理 HTTP POST 请求。这确保注销需要 CSRF 令牌，并且恶意用户无法强制注销您的用户。

最简单的方法是使用表单注销用户。如果您确实需要一个链接，可以使用 JavaScript 使链接执行 POST 操作（可能在一个隐藏表单上）。对于禁用 JavaScript 的浏览器，您可以选择让链接将用户带到执行 POST 操作的注销确认页面。

如果您确实想使用 HTTP GET 方法注销，也可以这样做。但是，请记住，这通常不推荐。例如，当使用任何 HTTP 方法请求/logout URL 时，以下代码会注销

使用任何 HTTP 方法注销

  • Java

  • Kotlin

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.logout((logout) -> logout
				.logoutRequestMatcher(new AntPathRequestMatcher("/logout"))
			);
		return http.build();
	}
}
import org.springframework.security.config.annotation.web.invoke

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            logout {
                logoutRequestMatcher = AntPathRequestMatcher("/logout")
            }
        }
        return http.build()
    }
}

有关更多信息，请参阅注销章节。

CSRF 和会话超时

默认情况下，Spring Security 使用HttpSessionCsrfTokenRepository将 CSRF 令牌存储在HttpSession中。这可能会导致会话过期的情况，从而没有 CSRF 令牌可以进行验证。

我们已经讨论了会话超时的通用解决方案。本节讨论与 servlet 支持相关的 CSRF 超时的具体细节。

您可以将 CSRF 令牌的存储更改为 cookie。有关详细信息，请参阅使用CookieCsrfTokenRepository部分。

如果令牌确实过期，您可能希望通过指定自定义AccessDeniedHandler来自定义其处理方式。自定义AccessDeniedHandler可以根据您的喜好处理InvalidCsrfTokenException。

多部分（文件上传）

我们已经讨论过如何保护多部分请求（文件上传）免受 CSRF 攻击会导致先有鸡还是先有蛋的问题。当 JavaScript 可用时，我们建议在 HTTP 请求标头中包含 CSRF 令牌以规避此问题。

如果 JavaScript 不可用，以下部分将讨论在 servlet 应用程序中将 CSRF 令牌放置在正文和URL中的选项。

您可以在 Spring 参考的多部分解析器部分和MultipartFilter javadoc中找到有关在 Spring 中使用多部分表单的更多信息。

将 CSRF 令牌放置在正文中

我们已经讨论过将 CSRF 令牌放置在正文中的权衡。在本节中，我们将讨论如何配置 Spring Security 从正文中读取 CSRF。

要从正文中读取 CSRF 令牌，请在 Spring Security 过滤器之前指定MultipartFilter。在 Spring Security 过滤器之前指定MultipartFilter意味着没有调用MultipartFilter的授权，这意味着任何人都可以在您的服务器上放置临时文件。但是，只有授权用户才能提交应用程序处理的文件。通常，这是推荐的方法，因为临时文件上传对大多数服务器的影响可以忽略不计。

配置MultipartFilter

  • Java

  • Kotlin

  • XML

public class SecurityApplicationInitializer extends AbstractSecurityWebApplicationInitializer {

	@Override
	protected void beforeSpringSecurityFilterChain(ServletContext servletContext) {
		insertFilters(servletContext, new MultipartFilter());
	}
}
class SecurityApplicationInitializer : AbstractSecurityWebApplicationInitializer() {
    override fun beforeSpringSecurityFilterChain(servletContext: ServletContext?) {
        insertFilters(servletContext, MultipartFilter())
    }
}
<filter>
	<filter-name>MultipartFilter</filter-name>
	<filter-class>org.springframework.web.multipart.support.MultipartFilter</filter-class>
</filter>
<filter>
	<filter-name>springSecurityFilterChain</filter-name>
	<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<filter-mapping>
	<filter-name>MultipartFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>
<filter-mapping>
	<filter-name>springSecurityFilterChain</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

为了确保使用 XML 配置在 Spring Security 过滤器之前指定MultipartFilter，您可以确保MultipartFilter的<filter-mapping>元素位于web.xml文件中的springSecurityFilterChain之前。

在 URL 中包含 CSRF 令牌

如果不允许未经授权的用户上传临时文件，另一种方法是在 Spring Security 过滤器之后放置MultipartFilter，并在表单的 action 属性中包含 CSRF 作为查询参数。由于CsrfToken作为名为_csrf的HttpServletRequest属性公开，因此我们可以使用它来创建一个包含 CSRF 令牌的action。以下示例使用 JSP 完成此操作

Action 中的 CSRF 令牌
<form method="post"
	action="./upload?${_csrf.parameterName}=${_csrf.token}"
	enctype="multipart/form-data">

HiddenHttpMethodFilter

我们已经讨论过将 CSRF 令牌放置在正文中的权衡。

在 Spring 的 Servlet 支持中，重写 HTTP 方法是通过使用HiddenHttpMethodFilter完成的。您可以在参考文档的HTTP 方法转换部分找到更多信息。

进一步阅读

现在您已经复习了 CSRF 保护，请考虑进一步了解漏洞利用保护，包括安全标头和HTTP 防火墙，或者继续学习如何测试您的应用程序。