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.
This section discusses Spring Security’s support for adding various security headers to the response of WebFlux.
Spring Security allows users to easily inject the default security headers to assist in protecting their application. The default for Spring Security is to include the following headers:
Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 ; includeSubDomains X-Frame-Options: DENY X-XSS-Protection: 1; mode=block
| Note |
|---|---|
|
Strict-Transport-Security is only added on HTTPS requests |
For additional details on each of these headers, refer to the corresponding sections:
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 want your HTTP response headers to look like the following:
Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0 X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN X-XSS-Protection: 1; mode=block
Specifically, you want all of the default headers with the following customizations:
- X-Frame-Options to allow any request from same domain
- HTTP Strict Transport Security (HSTS) will not be added to the response
You can easily do this with the following Java Configuration:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .hsts(hsts -> hsts .disable() ) .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 and XML based configuration is provided below:
If necessary, you can disable all of the HTTP Security response headers with the following Java Configuration:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .disable() ); return http.build(); }
In the past Spring Security required you to provide your own cache control for your web application. This seemed reasonable at the time, but browser caches have evolved to include caches for secure connections as well. This means that a user may view an authenticated page, log out, and then a malicious user can use the browser history to view the cached page. To help mitigate this Spring Security has added cache control support which will insert the following headers into you response by default.
Cache-Control: no-cache, no-store, max-age=0, must-revalidate Pragma: no-cache Expires: 0
If you actually want to cache specific responses, your application can selectively set the cache control headers to override the header set by Spring Security. This is useful to ensure things like CSS, JavaScript, and images are properly cached.
You can also disable cache control using the following Java Configuration:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .cache(cache -> cache.disable()) ); return http.build(); }
Historically browsers, including Internet Explorer, would try to guess the content type of a request using content sniffing. This allowed browsers to improve the user experience by guessing the content type on resources that had not specified the content type. For example, if a browser encountered a JavaScript file that did not have the content type specified, it would be able to guess the content type and then execute it.
| Note |
|---|---|
|
== There are many additional things one should do (i.e. only display the document in a distinct domain, ensure Content-Type header is set, sanitize the document, etc) when allowing content to be uploaded. However, these measures are out of the scope of what Spring Security provides. It is also important to point out when disabling content sniffing, you must specify the content type in order for things to work properly. == |
The problem with content sniffing is that this allowed malicious users to use polyglots (i.e. a file that is valid as multiple content types) to execute XSS attacks. For example, some sites may allow users to submit a valid postscript document to a website and view it. A malicious user might create a postscript document that is also a valid JavaScript file and execute a XSS attack with it.
Content sniffing can be disabled by adding the following header to our response:
X-Content-Type-Options: nosniff
Just as with the cache control element, the nosniff directive is added by default. However, if need to disable the header, the following may be used:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .contentTypeOptions(contentTypeOptions -> contentTypeOptions.disable()) ); return http.build(); }
When you type in your bank’s website, do you enter mybank.example.com or do you enter https://mybank.example.com? If you omit the https protocol, you are potentially vulnerable to Man in the Middle attacks. Even if the website performs a redirect to https://mybank.example.com a malicious user could intercept the initial HTTP request and manipulate the response (i.e. redirect to https://mibank.example.com and steal their credentials).
Many users omit the https protocol and this is why HTTP Strict Transport Security (HSTS) was created. Once mybank.example.com is added as a HSTS host, a browser can know ahead of time that any request to mybank.example.com should be interpreted as https://mybank.example.com. This greatly reduces the possibility of a Man in the Middle attack occurring.
| Note |
|---|---|
|
== In accordance with RFC6797, the HSTS header is only injected into HTTPS responses. In order for the browser to acknowledge the header, the browser must first trust the CA that signed the SSL certificate used to make the connection (not just the SSL certificate). == |
One way for a site to be marked as a HSTS host is to have the host preloaded into the browser. Another is to add the "Strict-Transport-Security" header to the response. For example the following would instruct the browser to treat the domain as an HSTS host for a year (there are approximately 31536000 seconds in a year):
Strict-Transport-Security: max-age=31536000 ; includeSubDomains ; preload
The optional includeSubDomains directive instructs Spring Security that subdomains (i.e. secure.mybank.example.com) should also be treated as an HSTS domain.
The optional preload directive instructs Spring Security that domain should be preloaded in browser as HSTS domain. For more details on HSTS preload please see https://hstspreload.org.
As with the other headers, Spring Security adds HSTS by default. You can customize HSTS headers 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(); }
Allowing your website to be added to a frame can be a security issue. For example, using clever CSS styling users could be tricked into clicking on something that they were not intending (video demo). For example, a user that is logged into their bank might click a button that grants access to other users. This sort of attack is known as Clickjacking.
| Note |
|---|---|
|
== Another modern approach to dealing with clickjacking is to use Section 22.2.7, “Content Security Policy (CSP)”. == |
There are a number ways to mitigate clickjacking attacks. For example, to protect legacy browsers from clickjacking attacks you can use frame breaking code. While not perfect, the frame breaking code is the best you can do for the legacy browsers.
A more modern approach to address clickjacking is to use X-Frame-Options header:
X-Frame-Options: DENY
The X-Frame-Options response header instructs the browser to prevent any site with this header in the response from being rendered within a frame. By default, Spring Security disables rendering within an iframe.
You can customize X-Frame-Options with Java Configuration using the following:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .frameOptions(frameOptions -> frameOptions .mode(SAMEORIGIN) ) ); return http.build(); }
Some browsers have built in support for filtering out reflected XSS attacks. This is by no means foolproof, but does assist in XSS protection.
The filtering is typically enabled by default, so adding the header typically just ensures it is enabled and instructs the browser what to do when a XSS attack is detected. For example, the filter might try to change the content in the least invasive way to still render everything. At times, this type of replacement can become a XSS vulnerability in itself. Instead, it is best to block the content rather than attempt to fix it. To do this we can add the following header:
X-XSS-Protection: 1; mode=block
This header is included by default. However, we can customize with Java Configuration with the following:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .xssProtection(xssProtection -> xssProtection.disable()) ); return http.build(); }
Content Security Policy (CSP) is a mechanism that web applications can leverage to mitigate content injection vulnerabilities, such as cross-site scripting (XSS). CSP is a declarative policy that provides a facility for web application authors to declare and ultimately inform the client (user-agent) about the sources from which the web application expects to load resources.
| Note |
|---|---|
|
== Content Security Policy is not intended to solve all content injection vulnerabilities. Instead, CSP can be leveraged to help reduce the harm caused by content injection attacks. As a first line of defense, web application authors should validate their input and encode their output. == |
A web application may employ the use of CSP by including one of the following HTTP headers in the response:
- Content-Security-Policy
- Content-Security-Policy-Report-Only
Each of these headers are used as a mechanism to deliver a security policy to the client. A security policy contains a set of security policy directives (for example, script-src and object-src), each responsible for declaring the restrictions for a particular resource representation.
For example, a web application can declare that it expects to load scripts from specific, trusted sources, by including the following header in the response:
Content-Security-Policy: script-src https://trustedscripts.example.com
An attempt to load a script from another source other than what is declared in the script-src directive will be blocked by the user-agent. Additionally, if the report-uri directive is declared in the security policy, then the violation will be reported by the user-agent to the declared URL.
For example, if a web application violates the declared security policy, the following response header will instruct the user-agent to send violation reports to the URL specified in the policy’s report-uri directive.
Content-Security-Policy: script-src https://trustedscripts.example.com; report-uri /csp-report-endpoint/
Violation reports are standard JSON structures that can be captured either by the web application’s own API or by a publicly hosted CSP violation reporting service, such as, REPORT-URI.
The Content-Security-Policy-Report-Only header provides the capability for web application authors and administrators to monitor security policies, rather than enforce them. This header is typically used when experimenting and/or developing security policies for a site. When a policy is deemed effective, it can be enforced by using the Content-Security-Policy header field instead.
Given the following response header, the policy declares that scripts may be loaded from one of two possible sources.
Content-Security-Policy-Report-Only: script-src 'self' https://trustedscripts.example.com; report-uri /csp-report-endpoint/
If the site violates this policy, by attempting to load a script from evil.com, the user-agent will send a violation report to the declared URL specified by the report-uri directive, but still allow the violating resource to load nevertheless.
It’s important to note that Spring Security does not add Content Security Policy by default. 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:
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:
@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:
@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(); }
Applying Content Security Policy to a web application is often a non-trivial undertaking. The following resources may provide further assistance in developing effective security policies for your site.
An Introduction to Content Security Policy
Referrer Policy is a mechanism that web applications can leverage to manage the referrer field, which contains the last page the user was on.
Spring Security’s approach is to use Referrer Policy header, which provides different policies:
Referrer-Policy: same-origin
The Referrer-Policy response header instructs the browser to let the destination knows the source where the user was previously.
Spring Security doesn’t add Referrer Policy header by default.
You can enable the Referrer-Policy header using Java configuration as shown below:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .referrerPolicy(referrerPolicy -> referrerPolicy .policy(ReferrerPolicy.SAME_ORIGIN) ) ); return http.build(); }
Feature Policy is a mechanism that allows web developers to selectively enable, disable, and modify the behavior of certain APIs and web features in the browser.
Feature-Policy: geolocation 'self'
With Feature Policy, developers can opt-in to a set of "policies" for the browser to enforce on specific features used throughout your site. These policies restrict what APIs the site can access or modify the browser’s default behavior for certain features.
Spring Security doesn’t add Feature Policy header by default.
You can enable the Feature-Policy header using Java configuration as shown below:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .headers(headers -> headers .featurePolicy("geolocation 'self'") ); return http.build(); }
Clear Site Data is a mechanism by which any browser-side data - cookies, local storage, and the like - can be removed when an HTTP response contains this header:
Clear-Site-Data: "cache", "cookies", "storage", "executionContexts"
This is a nice clean-up action to perform on logout.
Spring Security doesn’t add the Clear Site Data header by default.
You can configure your application to send down this header on logout like so:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { ServerLogoutHandler securityContext = new SecurityContextServerLogoutHandler(); ServerLogoutHandler clearSiteData = new HeaderWriterServerLogoutHandler(new ClearSiteDataServerHttpHeadersWriter()); DelegatingServerLogoutHandler logoutHandler = new DelegatingServerLogoutHandler(securityContext, clearSiteData); http // ... .logout() .logoutHandler(logoutHandler); return http.build(); }
| Note |
|---|---|
|
It’s not recommended that you configure this header writer via the |
HTTPS is required to provide a secure application. Spring Security can be configured to perform a redirect to https using the following Java Configuration:
@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:
@Bean SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { http // ... .redirectToHttps(redirectToHttps -> redirectToHttps .httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto")) ); return http.build(); }