Cross Site Request Forgery (CSRF) for WebFlux Environments

此小节讨论了 Spring Security 对 WebFlux 环境的 Cross Site Request Forgery (CSRF)支持。

This section discusses Spring Security’s Cross Site Request Forgery (CSRF) support for WebFlux environments.

Using Spring Security CSRF Protection

以下概述了使用 Spring Security 的 CSRF 防护的步骤：

The steps to using Spring Security’s CSRF protection are outlined below:

Use Proper HTTP Verbs

防止 CSRF 攻击的第一步是确保你的网站使用正确的 HTTP 动词。Safe Methods Must be Read-only中对此进行了详细介绍。

The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs. This is covered in detail in Safe Methods Must be Read-only.

Configure CSRF Protection

下一步是在你的应用程序中配置 Spring Security 的 CSRF 防护。默认情况下，Spring Security 的 CSRF 防护已启用，但你可能需要自定义配置。接下去的几个小节介绍了一些常见的自定义。

The next step is to configure Spring Security’s CSRF protection within your application. By default, Spring Security’s CSRF protection is enabled, but you may need to customize the configuration. The next few subsections cover a few common customizations.

Custom CsrfTokenRepository

默认情况下，Spring Security 使用 WebSessionServerCsrfTokenRepository 将预期的 CSRF 令牌存储在 WebSession 中。有时，你可能需要配置自定义 ServerCsrfTokenRepository。例如，你可能希望将 CsrfToken 持久化到 cookie 中以 support a JavaScript-based application。

By default, Spring Security stores the expected CSRF token in the WebSession by using WebSessionServerCsrfTokenRepository. Sometimes, you may need to configure a custom ServerCsrfTokenRepository. For example, you may want to persist the CsrfToken in a cookie to webflux-csrf-include-ajax-auto.

默认情况下，CookieServerCsrfTokenRepository 会写入名为 XSRF-TOKEN 的 cookie，并从名为 X-XSRF-TOKEN 的标头或 HTTP _csrf 参数中读取其内容。这些默认值来自 AngularJS

By default, the CookieServerCsrfTokenRepository writes to a cookie named XSRF-TOKEN and read its from a header named X-XSRF-TOKEN or the HTTP _csrf parameter. These defaults come from AngularJS

你可以在 Java 配置中配置 CookieServerCsrfTokenRepository：

You can configure CookieServerCsrfTokenRepository in Java Configuration:

Store CSRF Token in a Cookie

  • Java

  • Kotlin

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.csrf(csrf -> csrf.csrfTokenRepository(CookieServerCsrfTokenRepository.withHttpOnlyFalse()))
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        // ...
        csrf {
            csrfTokenRepository = CookieServerCsrfTokenRepository.withHttpOnlyFalse()
        }
    }
}

前面的范例明确设置了 cookieHttpOnly=false。这样做是必须的，以便 JavaScript（此例中为 AngularJS）可以读取它。如果不需要直接利用 JavaScript 读取 cookie 的功能，我们推荐省略 cookieHttpOnly=false（通过使用 new CookieServerCsrfTokenRepository() 替代）以增强安全性。

The preceding sample explicitly sets cookieHttpOnly=false. This is necessary to let JavaScript (in this case, AngularJS) to read it. If you do not need the ability to read the cookie with JavaScript directly, we recommend to omitting cookieHttpOnly=false (by using new CookieServerCsrfTokenRepository() instead) to improve security.

Disable CSRF Protection

默认情况下，已启用 CSRF 保护。但是，如果你 makes sense for your application，你可以禁用 CSRF 保护。

By default, CSRF protection is enabled. However, you can disable CSRF protection if it makes sense for your application.

下面的 Java 配置将禁用 CSRF 保护。

The Java configuration below will disable CSRF protection.

Disable CSRF Configuration

  • Java

  • Kotlin

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.csrf(csrf -> csrf.disable()))
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        // ...
        csrf {
            disable()
        }
    }
}

Configure ServerCsrfTokenRequestHandler

Spring Security 的 CsrfWebFilter 将一个 Mono<CsrfToken> 公开为一个 ServerWebExchange 属性，名称为 org.springframework.security.web.server.csrf.CsrfToken，借助一个 ServerCsrfTokenRequestHandler。在 5.8 中，默认实现是 ServerCsrfTokenRequestAttributeHandler，它只是使 Mono<CsrfToken> 可以作为交换属性使用。

Spring Security’s CsrfWebFilter exposes a Mono<CsrfToken> as a ServerWebExchange attribute named org.springframework.security.web.server.csrf.CsrfToken with the help of a ServerCsrfTokenRequestHandler. In 5.8, the default implementation was ServerCsrfTokenRequestAttributeHandler, which simply makes the Mono<CsrfToken> available as an exchange attribute.

从 6.0 起，默认实现是 XorServerCsrfTokenRequestAttributeHandler，它为 BREACH 提供保护（请参阅 gh-4001）。

As of 6.0, the default implementation is XorServerCsrfTokenRequestAttributeHandler, which provides protection for BREACH (see gh-4001).

如果你希望禁用 CsrfToken 的 BREACH 保护并恢复到 5.8 默认设置，则可以使用以下 Java 配置来配置 ServerCsrfTokenRequestAttributeHandler：

If you wish to disable BREACH protection of the CsrfToken and revert to the 5.8 default, you can configure ServerCsrfTokenRequestAttributeHandler using the following Java configuration:

Disable BREACH protection

  • Java

  • Kotlin

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.csrf(csrf -> csrf
			.csrfTokenRequestHandler(new ServerCsrfTokenRequestAttributeHandler())
		)
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        // ...
        csrf {
            csrfTokenRequestHandler = ServerCsrfTokenRequestAttributeHandler()
        }
    }
}

Include the CSRF Token

为了让 synchronizer token pattern防止 CSRF 攻击，我们必须在 HTTP 请求中包含实际的 CSRF 令牌。它必须包含在请求的一部分（表单参数、HTTP 标头或浏览器不会自动将其他选项包含在 HTTP 请求中）中。

For the synchronizer token pattern to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. It must be included in a part of the request (a form parameter, an HTTP header, or other option) that is not automatically included in the HTTP request by the browser.

We’ve seen 是 Mono<CsrfToken> 被暴露为 ServerWebExchange 属性。这意味着任何视图技术都可以访问 Mono<CsrfToken> 来将预期的令牌暴露为 form 或 meta tag。

webflux-csrf-configure-request-handler that the Mono<CsrfToken> is exposed as a ServerWebExchange attribute. This means that any view technology can access the Mono<CsrfToken> to expose the expected token as either a webflux-csrf-include-form-attr or a webflux-csrf-include-ajax-meta.

如果你的视图技术不提供一种订阅 Mono<CsrfToken> 的简单方式，则一个常见的模式是使用 Spring 的 @ControllerAdvice 直接暴露 CsrfToken。下面的范例将 CsrfToken 放在 Spring Security 的 CsrfRequestDataValueProcessor 自动包含的 CSRF 令牌的默认属性名称（_csrf）上，作为隐藏输入：

If your view technology does not provide a simple way to subscribe to the Mono<CsrfToken>, a common pattern is to use Spring’s @ControllerAdvice to expose the CsrfToken directly. The following example places the CsrfToken on the default attribute name (_csrf) used by Spring Security’s webflux-csrf-include-form-auto to automatically include the CSRF token as a hidden input:

CsrfToken as @ModelAttribute

  • Java

  • Kotlin

@ControllerAdvice
public class SecurityControllerAdvice {
	@ModelAttribute
	Mono<CsrfToken> csrfToken(ServerWebExchange exchange) {
		Mono<CsrfToken> csrfToken = exchange.getAttribute(CsrfToken.class.getName());
		return csrfToken.doOnSuccess(token -> exchange.getAttributes()
				.put(CsrfRequestDataValueProcessor.DEFAULT_CSRF_ATTR_NAME, token));
	}
}
@ControllerAdvice
class SecurityControllerAdvice {
    @ModelAttribute
    fun csrfToken(exchange: ServerWebExchange): Mono<CsrfToken> {
        val csrfToken: Mono<CsrfToken>? = exchange.getAttribute(CsrfToken::class.java.name)
        return csrfToken!!.doOnSuccess { token ->
            exchange.attributes[CsrfRequestDataValueProcessor.DEFAULT_CSRF_ATTR_NAME] = token
        }
    }
}

幸运的是，Thymeleaf 提供 integration，它可以在没有任何额外工作的情况下发挥作用。

Fortunately, Thymeleaf provides webflux-csrf-include-form-auto that works without any additional work.

Form URL Encoded

要发布 HTML 表单，CSRF 令牌必须包含在表单中作为隐藏输入。下面的范例展示了呈现的 HTML 可能是什么样子的：

To post an HTML form, the CSRF token must be included in the form as a hidden input. The following example shows what the rendered HTML might look like:

CSRF Token HTML
<input type="hidden"
	name="_csrf"
	value="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>

接下来，我们讨论将 CSRF 令牌作为表单中的隐藏输入包含进来的多种方法。

Next, we discuss various ways of including the CSRF token in a form as a hidden input.

Automatic CSRF Token Inclusion

Spring Security 的 CSRF 支持通过其 CsrfRequestDataValueProcessor 提供与 Spring 的 RequestDataValueProcessor 的集成。为了使 CsrfRequestDataValueProcessor 生效，必须订阅 Mono<CsrfToken> ，并且 CsrfToken 必须是与 DEFAULT_CSRF_ATTR_NAME 相匹配的 exposed as an attribute 。

Spring Security’s CSRF support provides integration with Spring’s RequestDataValueProcessor through its CsrfRequestDataValueProcessor. For CsrfRequestDataValueProcessor to work, the Mono<CsrfToken> must be subscribed to and the CsrfToken must be webflux-csrf-include-subscribe that matches DEFAULT_CSRF_ATTR_NAME.

幸运的是，Thymeleaf takes care of all the boilerplate 通过与 RequestDataValueProcessor 集成为您提供服务，以确保具有不安全 HTTP 方法（POST）的表单自动包含实际 CSRF 令牌。

Fortunately, Thymeleaf takes care of all the boilerplate for you by integrating with RequestDataValueProcessor to ensure that forms that have an unsafe HTTP method (POST) automatically include the actual CSRF token.

CsrfToken Request Attribute

如果用于在请求中包含实际 CSRF 令牌的 other options 不起作用，则你可以利用 Mono<CsrfToken> 以名为 org.springframework.security.web.server.csrf.CsrfToken 的 ServerWebExchange 属性的形式 is exposed 的事实。

If the webflux-csrf-include for including the actual CSRF token in the request do not work, you can take advantage of the fact that the Mono<CsrfToken> webflux-csrf-include as a ServerWebExchange attribute named org.springframework.security.web.server.csrf.CsrfToken.

下面的 Thymeleaf 范例假定你 expose 一个名为 _csrf 的属性上的 CsrfToken：

The following Thymeleaf sample assumes that you webflux-csrf-include-subscribe the CsrfToken on an attribute named _csrf:

CSRF Token in Form with Request Attribute
<form th:action="@{/logout}"
	method="post">
<input type="submit"
	value="Log out" />
<input type="hidden"
	th:name="${_csrf.parameterName}"
	th:value="${_csrf.token}"/>
</form>

Ajax and JSON Requests

如果你使用 JSON，你无法在 HTTP 参数中提交 CSRF 令牌。相反，你可以在 HTTP 头中提交令牌。

If you use JSON, you cannot submit the CSRF token within an HTTP parameter. Instead, you can submit the token within a HTTP header.

在以下部分中，我们讨论基于 JavaScript 的应用程序中将 CSRF 令牌作为 HTTP 请求头包含进来的多种方法。

In the following sections, we discuss various ways of including the CSRF token as an HTTP request header in JavaScript-based applications.

Automatic Inclusion

你可以使用 Spring Security 将预期的 CSRF 令牌存储在 cookie 中。通过将预期的 CSRF 存储在 cookie 中，像 AngularJS 等 JavaScript 框架会自动将实际的 CSRF 令牌包括在 HTTP 请求头中。

You can webflux-csrf-configure-custom-repository Spring Security to store the expected CSRF token in a cookie. By storing the expected CSRF in a cookie, JavaScript frameworks, such as AngularJS, automatically include the actual CSRF token in the HTTP request headers.

Meta Tags

另一个与 AngularJS 相似的模式是将 CSRF 令牌包含在你的 meta 标签中。HTML 可能看起来像这样：

An alternative pattern to webflux-csrf-include-form-auto is to include the CSRF token within your meta tags. The HTML might look something like this:

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

一旦 meta 标签包含了 CSRF 令牌，JavaScript 代码就能读取 meta 标签并将 CSRF 令牌作为头信息包含进去。如果你使用 jQuery，你可以使用以下代码来读取 meta 标签：

Once the meta tags contain the CSRF token, the JavaScript code can read the meta tags and include the CSRF token as a header. If you use jQuery, you could read the meta tags with the following code:

AJAX send CSRF Token
$(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);
	});
});

下面的示例假设你将 CSRF 令牌指定给了一个名为 csrfToken 的属性。下面的示例使用 Thymeleaf 来实现这一点：

The following sample assumes that you webflux-csrf-include-subscribe the CsrfToken on an attribute named _csrf. The following example does this with Thymeleaf:

CSRF meta tag JSP
<html>
<head>
	<meta name="_csrf" th:content="${_csrf.token}"/>
	<!-- default header name is X-CSRF-TOKEN -->
	<meta name="_csrf_header" th:content="${_csrf.headerName}"/>
	<!-- ... -->
</head>
<!-- ... -->

CSRF Considerations

在实现对 CSRF 攻击的保护时需要考虑一些特殊的注意事项。此小节讨论了与 WebFlux 环境相关的注意事项。请参阅 CSRF Considerations以获取更一般的讨论。

There are a few special considerations to consider when implementing protection against CSRF attacks. This section discusses those considerations as it pertains to WebFlux environments. See CSRF Considerations for a more general discussion.

Logging In

您应该 require CSRF for login 请求以防止伪造的登录尝试。Spring Security 的 WebFlux 支持自动执行此操作。

You should require CSRF for login requests to protect against forged login attempts. Spring Security’s WebFlux support automatically does this.

Logging Out

您应该 require CSRF for logout 请求以防止伪造注销尝试。默认情况下，Spring Security 的 LogoutWebFilter 仅处理 HTTP post 请求。这样可确保注销需要 CSRF 令牌，并且恶意用户无法强制注销您的用户。

You should require CSRF for logout requests to protect against forging logout attempts. By default, Spring Security’s LogoutWebFilter only processes only HTTP post requests. This ensures that logout requires a CSRF token and that a malicious user cannot forcibly log out your users.

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

The easiest approach is to use a form to log out. If you really want a link, you can use JavaScript to have the link perform a POST (maybe on a hidden form). For browsers with JavaScript that is disabled, you can optionally have the link take the user to a logout confirmation page that performs the POST.

如果你真的想对注销使用 HTTP GET，你也可以这么做，但请记住，通常不建议这样做。例如，以下 Java 配置会在使用任何 HTTP 方法请求 logout URL 时注销：

If you really want to use HTTP GET with logout, you can do so, but remember that doing so is generally not recommended. For example, the following Java Configuration logs out when the /logout URL is requested with any HTTP method:

Log out with HTTP GET

  • Java

  • Kotlin

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.logout(logout -> logout.requiresLogout(new PathPatternParserServerWebExchangeMatcher("/logout")))
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        // ...
        logout {
            requiresLogout = PathPatternParserServerWebExchangeMatcher("/logout")
        }
    }
}

CSRF and Session Timeouts

默认情况下，Spring Security 会将 CSRF 令牌存储在会话中。这种安排可能导致会话过期的情况，这意味着没有预期的 CSRF 令牌可以用于验证。

By default, Spring Security stores the CSRF token in the WebSession. This arrangement can lead to a situation where the session expires, which means that there is not an expected CSRF token to validate against.

我们已经讨论了 general solutions 至会话超时。本节讨论 CSRF 超时的具体信息，因为它与 WebFlux 支持相关。

We have already discussed general solutions to session timeouts. This section discusses the specifics of CSRF timeouts as it pertains to the WebFlux support.

你可以将预期的 CSRF 令牌的存储更改为 cookie。有关详细信息，请参阅 CSRF 令牌存储部分。

You can change storage of the expected CSRF token to be in a cookie. For details, see the Custom CsrfTokenRepository section.

Multipart (file upload)

我们已经 already discussed 了如何保护 multipart 请求（文件上传）免受 CSRF 攻击导致的 chicken and the egg 问题。本节讨论如何在 WebFlux 应用程序中实施将 CSRF 令牌置于 body 和 url 中。

We have already discussed how protecting multipart requests (file uploads) from CSRF attacks causes a chicken and the egg problem. This section discusses how to implement placing the CSRF token in the webflux-csrf-considerations-multipart-body and webflux-csrf-considerations-multipart-url within a WebFlux application.

有关在 Spring 中使用多部分表单的详细信息，请参阅 Spring 参考的 multipart/form-data 部分。

For more information about using multipart forms with Spring, see the Multipart Data section of the Spring reference.

Place CSRF Token in the Body

我们已经 already discussed 了将 CSRF 令牌放入正文中的权衡取舍。

We have already discussed the trade-offs of placing the CSRF token in the body.

在 WebFlux 应用程序中，你可以使用以下配置来做到这一点：

In a WebFlux application, you can do so with the following configuration:

Enable obtaining CSRF token from multipart/form-data

  • Java

  • Kotlin

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.csrf(csrf -> csrf.tokenFromMultipartDataEnabled(true))
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
		// ...
        csrf {
            tokenFromMultipartDataEnabled = true
        }
    }
}

Include CSRF Token in URL

我们已经 already discussed 了将 CSRF 令牌放入 URL 中的权衡取舍。由于 CsrfToken 公开为 ServerHttpRequest request attribute，我们可以使用它创建其中包含 CSRF 令牌的 action。下面演示了使用 Thymeleaf 的示例：

We have already discussed the trade-offs of placing the CSRF token in the URL. Since the CsrfToken is exposed as an ServerHttpRequest webflux-csrf-include, we can use that to create an action with the CSRF token in it. An example with Thymeleaf is shown below:

CSRF Token in Action
<form method="post"
	th:action="@{/upload(${_csrf.parameterName}=${_csrf.token})}"
	enctype="multipart/form-data">

HiddenHttpMethodFilter

我们已经 already discussed 覆盖了 HTTP 方法。

We have already discussed overriding the HTTP method.

在 Spring WebFlux 应用程序中，可以通过使用 Spring Security 提供的 CSRF matcher（例如、DefaultCsrfMatcher 或 RequestDataValueCsrfMatcher）来覆盖 HTTP 方法。

In a Spring WebFlux application, overriding the HTTP method is done by using HiddenHttpMethodFilter.