This section discusses Spring Security’s Cross Site Request Forgery (CSRF) support for WebFlux environments.
The steps to using Spring Security’s CSRF protection are outlined below:
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 Idempotent.
The next step is to configure Spring Security’s CSRF protection within your application. Spring Security’s CSRF protection is enabled by default, but you may need to customize the configuration. Below are a few common customizations.
By default Spring Security stores the expected CSRF token in the WebSession using WebSessionServerCsrfTokenRepository.
There can be cases where users will want to configure a custom ServerCsrfTokenRepository.
For example, it might be desirable to persist the CsrfToken in a cookie to support a JavaScript based application.
By default the CookieServerCsrfTokenRepository will write to a cookie named XSRF-TOKEN and read it from a header named X-XSRF-TOKEN or the HTTP parameter _csrf.
These defaults come from AngularJS
You can configure CookieCsrfTokenRepository in Java Configuration using:
Example 22.1. Store CSRF Token in a Cookie with Java Configuration
@Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .csrf(csrf -> csrf.csrfTokenRepository(CookieServerCsrfTokenRepository.withHttpOnlyFalse())) return http.build(); }
![[Note]](images/note.png) | Note |
|---|---|
|
The sample explicitly sets |
CSRF protection is enabled by default. However, it is simple to disable CSRF protection if it makes sense for your application.
The Java configuration below will disable CSRF protection.
Example 22.2. Disable CSRF Java Configuration
@Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .csrf(csrf -> csrf.disable())) return http.build(); }
In order for the synchronizer token pattern to protect against CSRF attacks, we must include the actual CSRF token in the HTTP request. This must be included in a part of the request (i.e. form parameter, HTTP header, etc) that is not automatically included in the HTTP request by the browser.
Spring Security’s CsrfWebFilter exposes a Mono<CsrfToken> as a ServerWebExchange attribute named org.springframework.security.web.server.csrf.CsrfToken.
This means that any view technology can access the Mono<CsrfToken> to expose the expected token as either a form or meta tag.
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.
For example, the following code will place the CsrfToken on the default attribute name (_csrf) used by Spring Security’s CsrfRequestDataValueProcessor to automatically include the CSRF token as a hidden input.
Example 22.3. CsrfToken as @ModelAttribute
@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)); } }
Fortunately, Thymeleaf provides integration that works without any additional work.
In order to post an HTML form the CSRF token must be included in the form as a hidden input. For example, the rendered HTML might look like:
Example 22.4. CSRF Token HTML
<input type="hidden" name="_csrf" value="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
Next we will discuss various ways of including the CSRF token in a form as a hidden input.
Spring Security’s CSRF support provides integration with Spring’s RequestDataValueProcessor via its CsrfRequestDataValueProcessor.
In order for CsrfRequestDataValueProcessor to work, the Mono<CsrfToken> must be subscribed to and the CsrfToken must be exposed as an attribute that matches DEFAULT_CSRF_ATTR_NAME.
Fortunately, Thymleaf provides support to take care of all the boilerplate for you by integrating with RequestDataValueProcessor to ensure that forms that have an unsafe HTTP method (i.e. post) will automatically include the actual CSRF token.
If the other options for including the actual CSRF token in the request do not work, you can take advantage of the fact that the Mono<CsrfToken> is exposed as a ServerWebExchange attribute named org.springframework.security.web.server.csrf.CsrfToken.
The Thymeleaf sample below assumes that you expose the CsrfToken on an attribute named _csrf.
Example 22.5. 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>
If you are using JSON, then it is not possible to submit the CSRF token within an HTTP parameter. Instead you can submit the token within a HTTP header.
In the following sections we will discuss various ways of including the CSRF token as an HTTP request header in JavaScript based applications.
Spring Security can easily be configured to store the expected CSRF token in a cookie. By storing the expected CSRF in a cookie, JavaScript frameworks like AngularJS will automatically include the actual CSRF token in the HTTP request headers.
An alternative pattern to exposing the CSRF in a cookie is to include the CSRF token within your meta tags.
The HTML might look something like this:
Example 22.6. CSRF meta tag HTML
<html>
<head>
<meta name="_csrf" content="4bfd1575-3ad1-4d21-96c7-4ef2d9f86721"/>
<meta name="_csrf_header" content="X-CSRF-TOKEN"/>
<!-- ... -->
</head>
<!-- ... -->
Once the meta tags contained the CSRF token, the JavaScript code would read the meta tags and include the CSRF token as a header. If you were using jQuery, this could be done with the following:
Example 22.7. 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); }); });
The sample below assumes that you expose the CsrfToken on an attribute named _csrf.
An example of doing this with Thymeleaf is shown below:
Example 22.8. 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>
<!-- ... -->
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. Refer to the section called “CSRF Considerations” for a more general discussion.
It is important to require CSRF for log in requests to protect against forging log in attempts. Spring Security’s WebFlux support does this out of the box.
It is important to require CSRF for log out requests to protect against forging log out attempts.
By default Spring Security’s LogoutWebFilter only processes HTTP post requests.
This ensures that log out requires a CSRF token and that a malicious user cannot forcibly log out your users.
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 (i.e. maybe on a hidden form). For browsers with JavaScript that is disabled, you can optionally have the link take the user to a log out confirmation page that will perform the POST.
If you really want to use HTTP GET with logout you can do so, but remember this is generally not recommended.
For example, the following Java Configuration will perform logout with the URL /logout is requested with any HTTP method:
Example 22.9. Log out with HTTP GET
@Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .logout(logout -> logout.requiresLogout(new PathPatternParserServerWebExchangeMatcher("/logout"))) return http.build(); }
By default Spring Security stores the CSRF token in the WebSession.
This can lead to a situation where the session expires which means there is not an expected CSRF token to validate against.
We’ve already discussed general solutions to session timeouts. This section discusses the specifics of CSRF timeouts as it pertains to the WebFlux support.
It is simple to change storage of the expected CSRF token to be in a cookie. For details, refer to the the section called “Custom CsrfTokenRepository” section.
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 body and url within a WebFlux application.
| Note |
|---|---|
|
More information about using multipart forms with Spring can be found within the Multipart Data section of the Spring reference. |
We have already discussed the trade-offs of placing the CSRF token in the body.
In a WebFlux application, this can be configured with the following configuration:
Example 22.10. Enable obtaining CSRF token from multipart/form-data
@Bean public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .csrf(csrf -> csrf.tokenFromMultipartDataEnabled(true)) return http.build(); }
We have already discussed the trade-offs of placing the CSRF token in the URL.
Since the CsrfToken is exposed as an ServerHttpRequest request attribute, we can use that to create an action with the CSRF token in it.
An example with Thymeleaf is shown below:
Example 22.11. CSRF Token in Action
<form method="post" th:action="@{/upload(${_csrf.parameterName}=${_csrf.token})}" enctype="multipart/form-data">
We have already discussed overriding the HTTP method.
In a Spring WebFlux application, overriding the HTTP method is done using HiddenHttpMethodFilter.
Security HTTP Response Headers can be used to increase the security of web applications. This section is dedicated to WebFlux based support for Security HTTP Response Headers.
Spring Security provides a default set of Security HTTP Response Headers to provide secure defaults. While each of these headers are considered best practice, it should be noted that not all clients utilize the headers, so additional testing is encouraged.
You can customize specific headers.
For example, assume that you want the defaults except you wish to specify SAMEORIGIN for X-Frame-Options.
You can easily do this with the following Java Configuration:
Example 22.12. Customize Default Security Headers with Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .frameOptions(frameOptions -> frameOptions .mode(Mode.SAMEORIGIN) ) ); return http.build(); }
If you do not want the defaults to be added and want explicit control over what should be used, you can disable the defaults. An example for both Java configuration is provided below:
Example 22.13. Disable HTTP Security Response Headers
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .disable() ); return http.build(); }
Spring Security includes Cache Control headers by default.
However, if you actually want to cache specific responses, your application can selectively add them to the ServerHttpResponse to override the header set by Spring Security. This is useful to ensure things like CSS, JavaScript, and images are properly cached.
When using Spring WebFluxZz, this is typically done within your configuration. Details on how to do this can be found in the Static Resources portion of the Spring Reference documentation
If necessary, you can also disable Spring Security’s cache control HTTP response headers.
Example 22.14. Cache Control Disabled
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .cache(cache -> cache.disable()) ); return http.build(); }
Spring Security includes Content-Type headers by default. However, you can disable it in Java Configuration with:
Example 22.15. Content Type Options Disabled with Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .contentTypeOptions(contentTypeOptions -> contentTypeOptions.disable()) ); return http.build(); }
Spring Security provides the Strict Transport Security header by default. However, you can customize the results explicitly. For example, the following is an example of explicitly providing HSTS with Java Configuration:
Example 22.16. Strict Transport Security with Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .hsts(hsts -> hsts .includeSubdomains(true) .preload(true) .maxAge(Duration.ofDays(365)) ) ); return http.build(); }
By default, Spring Security disables rendering within an iframe using X-Frame-Options.
You can customize frame options to use the same origin within Java Configuration using the following:
Example 22.17. X-Frame-Options: SAMEORIGIN
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .frameOptions(frameOptions -> frameOptions .mode(SAMEORIGIN) ) ); return http.build(); }
By default, Spring Security instructs browsers to block reflected XSS attacks using the <<headers-xss-protection,X-XSS-Protection header>.
You can disable X-XSS-Protection with the following Java Configuration:
Example 22.18. X-XSS-Protection Customization
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .xssProtection(xssProtection -> xssProtection.disable()) ); return http.build(); }
Spring Security does not add Content Security Policy by default, because a reasonable default is impossible to know without context of the application. The web application author must declare the security policy(s) to enforce and/or monitor for the protected resources.
For example, given the following security policy:
Example 22.19. Content Security Policy Example
Content-Security-Policy: script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/
You can enable the CSP header using Java configuration as shown below:
Example 22.20. Content Security Policy
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .contentSecurityPolicy(contentSecurityPolicy -> contentSecurityPolicy .policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/") ) ); return http.build(); }
To enable the CSP report-only header, provide the following Java configuration:
Example 22.21. Content Security Policy Report Only
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .contentSecurityPolicy(contentSecurityPolicy -> contentSecurityPolicy .policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/") .reportOnly() ) ); return http.build(); }
Spring Security does not add Referrer Policy headers by default. You can enable the Referrer Policy header using Java configuration as shown below:
Example 22.22. Referrer Policy Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .referrerPolicy(referrerPolicy -> referrerPolicy .policy(ReferrerPolicy.SAME_ORIGIN) ) ); return http.build(); }
Spring Security does not add Feature Policy headers by default.
The following Feature-Policy header:
can enable the Feature Policy header using Java configuration as shown below:
Example 22.24. Feature-Policy Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .featurePolicy("geolocation 'self'") ); return http.build(); }
Spring Security does not add Clear-Site-Data headers by default. The following Clear-Site-Data header:
can be sent on log out with the following configuration:
Example 22.26. Clear-Site-Data Java Configuration
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { ServerLogoutHandler securityContext = new SecurityContextServerLogoutHandler(); ClearSiteDataServerHttpHeadersWriter writer = new ClearSiteDataServerHttpHeadersWriter(CACHE, COOKIES); ServerLogoutHandler clearSiteData = new HeaderWriterServerLogoutHandler(writer); DelegatingServerLogoutHandler logoutHandler = new DelegatingServerLogoutHandler(securityContext, clearSiteData); http // ... .logout() .logoutHandler(logoutHandler); return http.build(); }
All HTTP based communication should be protected using TLS.
Below you can find details around WebFlux specific features that assist with HTTPS usage.
If a client makes a request using HTTP rather than HTTPS, Spring Security can be configured to redirect to HTTPS.
For example, the following Java configuration will redirect any HTTP requests to HTTPS:
Example 22.27. Redirect to HTTPS
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .redirectToHttps(withDefaults()); return http.build(); }
The configuration can easily be wrapped around an if statement to only be turned on in production.
Alternatively, it can be enabled by looking for a property about the request that only happens in production.
For example, if the production environment adds a header named X-Forwarded-Proto the following Java Configuration could be used:
Example 22.28. Redirect to HTTPS when X-Forwarded
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .redirectToHttps(redirectToHttps -> redirectToHttps .httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto")) ); return http.build(); }
Spring Security provides support for Strict Transport Security and enables it by default.
Spring Security integrates with proxy servers.