Cross Site Request Forgery (CSRF) for WebFlux Environments

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

Using Spring Security CSRF Protection

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

webflux-csrf-read-only
webflux-csrf-configure
webflux-csrf-include

Use Proper HTTP Verbs

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

Configure CSRF Protection

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

Custom CsrfTokenRepository

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

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

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

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() 替代）以增强安全性。

Disable CSRF Protection

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

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

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> 可以作为交换属性使用。

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

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

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 请求中）中。

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

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，它可以在没有任何额外工作的情况下发挥作用。

Form URL Encoded

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

CSRF Token HTML

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

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

Automatic CSRF Token Inclusion

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

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

CsrfToken Request Attribute

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

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

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 头中提交令牌。

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

Automatic Inclusion

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

Meta Tags

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

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 标签：

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 来实现这一点：

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以获取更一般的讨论。

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

Logging Out

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

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

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

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 令牌可以用于验证。

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

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

Multipart (file upload)

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

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

Place CSRF Token in the Body

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

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

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 的示例：

CSRF Token in Action

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

HiddenHttpMethodFilter

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

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