跨站点请求伪造（CSRF） (Cross Site Request Forgery (CSRF)) _ Spring Security6.3.1中文文档(官方文档中文翻译)|Spring 教程 —

在最终用户可以登录的应用程序中，请务必考虑如何防止跨站点请求伪造（CSRF）。

默认情况下，Spring Security 会针对不安全的 HTTP 方法（例如 POST 请求）防止 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 保护的组件
我需要将应用程序从 Spring Security 5 迁移到 6
我想将 CsrfToken 存储在 cookie 中而不是会话中
我想将 CsrfToken 存储在自定义位置
我想选择退出延期令牌
我想退出 BREACH 保护
我需要将 Thymeleaf、JSP 或其他视图技术与后端集成的指导
我需要将 Angular 或其他 JavaScript 框架与后端集成的指导
我需要将移动应用程序或其他客户端与后端集成的指导
我需要有关处理错误的指导
我想测试 CSRF 保护
我需要有关禁用 CSRF 保护的指导

了解 CSRF 保护的组件

CSRF 保护由 CsrfFilter 中的几个组件提供：

图 1. 组件CsrfFilter

CSRF保护分为两部分：

通过委托给 CsrfTokenRequestHandler，使 CsrfToken 可供应用程序使用。
确定请求是否需要 CSRF 保护，加载并验证令牌，并处理 AccessDeniedException。

图2. 加工CsrfFilter

首先，加载 DeferredCsrfToken，它包含对 CsrfTokenRepository 的引用，以便稍后可以加载持久化的内容（在中）。CsrfToken
其次，将一个（创建自）提供给 CsrfTokenRequestHandler，该 CsrfTokenRequestHandler 负责填充请求属性，使其可供应用程序的其余部分使用。Supplier<CsrfToken>DeferredCsrfTokenCsrfToken
接下来，主 CSRF 保护处理开始并检查当前请求是否需要 CSRF 保护。如果不需要，则继续过滤链并结束处理。
如果需要 CSRF 保护，则最终从 .CsrfTokenDeferredCsrfToken
继续，客户端提供的实际 CSRF 令牌（如果有）使用 CsrfTokenRequestHandler 进行解析。
将实际的 CSRF 令牌与持久的 .如果有效，则继续筛选链并结束处理。CsrfToken
如果实际的 CSRF 令牌无效（或缺失），则将 an 传递给 AccessDeniedHandler 并结束处理。AccessDeniedException

迁移到 Spring Security 6

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

现在默认情况下会延迟加载，以提高性能，不再需要在每个请求上加载会话。CsrfToken
现在默认情况下，每个请求都包含随机性，以保护 CSRF 令牌免受 BREACH 攻击。CsrfToken

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

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

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

将`CsrfToken`

使用 .CsrfTokenCsrfTokenRepository

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

使用`HttpSessionCsrfTokenRepository`

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

默认情况下，从名为 HTTP 请求标头或请求参数的 HTTP 请求标头中读取令牌。HttpSessionCsrfTokenRepositoryX-CSRF-TOKEN_csrf

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

配置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"/>

使用`CookieCsrfTokenRepository`

您可以使用 CookieCsrfTokenRepository 在 cookie 中保留它以支持基于 JavaScript 的应用程序。CsrfToken

写入名为的 cookie，并从 HTTP 请求标头或 request 参数中读取它。这些默认值来自 Angular 及其前身 AngularJS。CookieCsrfTokenRepositoryXSRF-TOKENX-XSRF-TOKEN_csrf

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

您可以使用以下配置进行配置：CookieCsrfTokenRepository

配置CookieCsrfTokenRepository

Java
Kotlin
XML

@Configuration
@EnableWebSecurity
public class SecurityConfig {

	@Bean
	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
		http
			// ...
			.csrf((csrf) -> csrf
				.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
			);
		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 = CookieCsrfTokenRepository.withHttpOnlyFalse()
            }
        }
        return http.build()
    }
}

<http>
	<!-- ... -->
	<csrf token-repository-ref="tokenRepository"/>
</http>
<b:bean id="tokenRepository"
	class="org.springframework.security.web.csrf.CookieCsrfTokenRepository"
	p:cookieHttpOnly="false"/>

该示例显式设置为。这是让 JavaScript 框架（如 Angular）读取它所必需的。如果您不需要直接使用 JavaScript 读取 cookie，我们建议省略（改用）以提高安全性。HttpOnlyfalseHttpOnlynew CookieCsrfTokenRepository()

自定义`CsrfTokenRepository`

在某些情况下，您可能希望实现自定义 CsrfTokenRepository。

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

配置自定义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"/>

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

处理`CsrfToken`

可供应用程序使用 . 此组件还负责解析 from HTTP 标头或请求参数。CsrfTokenCsrfTokenRequestHandlerCsrfToken

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

使用（BREACH）`XorCsrfTokenRequestAttributeHandler`

它使作为称为的属性可用，并且还为 BBREACH 提供保护。XorCsrfTokenRequestAttributeHandlerCsrfTokenHttpServletRequest_csrf

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

此实现还将请求中的令牌值解析为请求标头（默认情况下是 X-CSRF-TOKEN 或 X-XSRF-TOKEN 之一）或请求参数（默认情况下）。_csrf

通过将随机性编码到 CSRF 令牌值中来提供 BREACH 保护，以确保每个请求返回的更改。当令牌稍后解析为标头值或请求参数时，将对其进行解码以获取原始令牌，然后将其与持久化的 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`

使可用作称为的属性。CsrfTokenRequestAttributeHandlerCsrfTokenHttpServletRequest_csrf

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

此实现还将请求中的令牌值解析为请求标头（默认情况下是 X-CSRF-TOKEN 或 X-XSRF-TOKEN 之一）或请求参数（默认情况下）。_csrf

其主要用途是选择退出的 BREACH 保护，可以使用以下配置进行配置：CsrfTokenRequestAttributeHandlerCsrfToken

选择退出 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

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

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

配置自定义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"/>

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

延迟加载`CsrfToken`

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

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

由于 Spring Security 默认情况下也会存储 in 中，因此延迟的 CSRF 令牌可以通过不需要在每个请求上加载会话来提高性能。CsrfTokenHttpSession

如果要选择退出延迟令牌并导致在每个请求上加载令牌，则可以使用以下配置执行此操作：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>

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

与 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）的表单中：

Spring 的表单标签库
百里香叶
与 RequestDataValueProcessor 集成的任何其他视图技术（通过 CsrfRequestDataValueProcessor)
您也可以通过 csrfInput 标记自行包含令牌

如果这些选项不可用，则可以利用公开为名为 _csrf 的 HttpServletRequest 属性这一事实。以下示例使用 JSP 执行此操作：CsrfToken

具有请求属性的 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，则可以在 HTTP 请求标头中提交 CSRF 令牌，而不是请求参数。

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

在将单页应用程序（SPA）与 Spring Security 的 CSRF 保护集成时，BREACH 保护和延迟令牌有特殊注意事项。下一节将提供完整的配置示例。

您可以在以下部分中了解不同类型的 JavaScript 应用程序：

单页应用程序

将单页应用程序（SPA）与 Spring Security 的 CSRF 保护集成时，有一些特殊的注意事项。

回想一下，Spring Security 默认情况下提供 CsrfToken 的 BREACH 保护。在 Cookie 中存储预期的 CSRF 令牌时，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	配置为，以便 JavaScript 应用程序可以读取 cookie。`CookieCsrfTokenRepositoryHttpOnlyfalse`
2	配置一个自定义，该自定义器根据 CSRF 令牌是 HTTP 请求标头（）还是请求参数（）来解析 CSRF 令牌。`CsrfTokenRequestHandlerX-XSRF-TOKEN_csrf`
3	配置自定义以在每个请求上加载，如果需要，它将返回一个新的 cookie。`FilterCsrfToken`

多页应用程序

对于在每个页面上加载 JavaScript 的多页面应用程序，在 Cookie 中公开 CSRF 令牌的替代方法是在标记中包含 CSRF 令牌。 HTML 可能如下所示：meta

HTML 元标记中的 CSRF 令牌

<html>
<head>
	<meta name="_csrf" content="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
	<meta name="_csrf_header" content="X-CSRF-TOKEN"/>
	<!-- ... -->
</head>
<!-- ... -->
</html>

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

具有请求属性的 HTML 元标记中的 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 应用程序的另一个选项是在 HTTP 响应标头中包含 CSRF 令牌。

实现此目的的一种方法是将与 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)
	}

}

由于这适用于应用程序中的所有终结点，因此将导致在每个请求上加载 CSRF 令牌，这可能会在使用 HttpSessionCsrfTokenRepository 时否定延迟令牌的好处。但是，在使用 CookieCsrfTokenRepository 时，这通常不是问题。@ControllerAdvice

请务必记住，控制器端点和控制器建议是在 Spring Security 过滤器链之后调用的。这意味着，仅当请求通过筛选器链传递到应用程序时，才会应用此功能。有关向筛选器链添加筛选器以便更早访问的示例，请参阅单页应用程序的配置。@ControllerAdviceHttpServletResponse

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

移动应用程序

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

但是，同时提供浏览器流量并因此仍需要 CSRF 保护的后端应用程序可能会继续存储在会话中而不是 cookie 中。CsrfToken

在这种情况下，与后端集成的典型模式是公开端点，以允许前端（移动或浏览器客户端）按需请求 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 令牌。

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

在将单页应用程序（SPA）与 Spring Security 的 CSRF 保护集成时，BREACH 保护和延迟令牌有特殊注意事项。下一节将提供完整的配置示例。

1	配置为，以便 JavaScript 应用程序可以读取 cookie。`CookieCsrfTokenRepositoryHttpOnlyfalse`
2	配置一个自定义，该自定义器根据 CSRF 令牌是 HTTP 请求标头（）还是请求参数（）来解析 CSRF 令牌。`CsrfTokenRequestHandlerX-XSRF-TOKEN_csrf`
3	配置自定义以在每个请求上加载，如果需要，它将返回一个新的 cookie。`FilterCsrfToken`

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

处理`AccessDeniedException`

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

配置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将仅处理HTTP POST请求。这可确保注销需要 CSRF 令牌，并且恶意用户无法强制注销您的用户。LogoutFilter

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

如果您确实想将 HTTP GET 与注销一起使用，您可以这样做。但是，请记住，通常不建议这样做。例如，当使用任何 HTTP 方法请求 URL 时，以下内容将注销：/logout

使用任何 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 将 CSRF 令牌存储在 using HttpSessionCsrfTokenRepository 中。这可能会导致会话过期，没有 CSRF 令牌可供验证。HttpSession

我们已经讨论了会话超时的一般解决方案。本节讨论 CSRF 超时的细节，因为它与 servlet 支持有关。

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

如果令牌确实过期，您可能希望通过指定自定义 AccessDeniedHandler 来自定义它的处理方式。自定义可以按照您喜欢的任何方式进行处理。AccessDeniedHandlerInvalidCsrfTokenException

分片（文件上传）

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

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

您可以在 Spring 参考的 Multipart Resolver 部分和 MultipartFilter javadoc 中找到有关将多部分表单与 Spring 配合使用的更多信息。

将 CSRF 令牌放在正文中

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

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

配置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<filter-mapping>MultipartFilterspringSecurityFilterChainweb.xml

在 URL 中包含 CSRF 令牌

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

CSRF 代币在行动

<form method="post"
	action="./upload?${_csrf.parameterName}=${_csrf.token}"
	enctype="multipart/form-data">

HiddenHttpMethodFilter

我们已经讨论了将 CSRF 代币放入正文中的权衡。

在 Spring 的 Servlet 支持中，使用 HiddenHttpMethodFilter 覆盖 HTTP 方法。您可以在参考文档的 HTTP 方法转换部分找到更多信息。

您可以在 Spring 参考的 Multipart Resolver 部分和 MultipartFilter javadoc 中找到有关将多部分表单与 Spring 配合使用的更多信息。

延伸阅读

现在，您已经查看了 CSRF 保护，请考虑了解有关漏洞利用保护（包括安全标头和 HTTP 防火墙）的更多信息，或者继续学习如何测试应用程序。

了解 CSRF 保护的组件

迁移到 Spring Security 6

将CsrfToken

使用HttpSessionCsrfTokenRepository

使用CookieCsrfTokenRepository

自定义CsrfTokenRepository

处理CsrfToken

使用 （BREACH）XorCsrfTokenRequestAttributeHandler

使用CsrfTokenRequestAttributeHandler

自定义CsrfTokenRequestHandler

延迟加载CsrfToken

与 CSRF 保护集成

HTML 表单

JavaScript 应用程序

单页应用程序

多页应用程序

其他 JavaScript 应用程序

移动应用程序

处理AccessDeniedException

CSRF测试

禁用 CSRF 保护

CSRF 注意事项

登录

注销

CSRF 和会话超时

分片（文件上传）

将 CSRF 令牌放在正文中

在 URL 中包含 CSRF 令牌

HiddenHttpMethodFilter

延伸阅读

将`CsrfToken`

使用`HttpSessionCsrfTokenRepository`

使用`CookieCsrfTokenRepository`

自定义`CsrfTokenRepository`

处理`CsrfToken`

使用（BREACH）`XorCsrfTokenRequestAttributeHandler`

使用`CsrfTokenRequestAttributeHandler`

自定义`CsrfTokenRequestHandler`

延迟加载`CsrfToken`

处理`AccessDeniedException`