diff --git a/docs/manual/src/docbook/headers.xml b/docs/manual/src/docbook/headers.xml new file mode 100644 index 0000000000..1b3ddecd8e --- /dev/null +++ b/docs/manual/src/docbook/headers.xml @@ -0,0 +1,282 @@ + + + Security Headers + + This section discusses Spring Security's support for adding various security headers to the response. +
+ Default Security Headers + Spring Security allows users to easily inject the default security headers to assist in protecting their + application. + + + Cache Control + + + Content Type Options + + + HTTP Strict Transport Security + + + X-Frame-Options + + + X-XSS-Protection + + + 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. If you are using Spring Security's XML namespace support, + you can easily add all of the default headers with the + <headers> element with no child elements: + + ... + +]]> + If you are using Spring Security's Java configuration, all of the default security headers are added by default. + They can be disabled using the Java configuration below: + +
+
+ Cache Control + 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. + + Simply adding the <headers /> element with no child elements will + automatically add Cache Control and quite a few other protections. However, if you only want cache control, you can + enable this feature using Spring Security's XML namespace with the + <cache-control /> element. + + ... + + + +]]> + Similarly, you can enable only cache control within Java Configuration with the following: + + If you actually want to cache specific responses, your application can selectively invoke + HttpServletResponse.setHeader(String,String) + 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 Web MVC, this is typically done within your configuration. For example, the following configuration will + ensure that the cache headers are set for all of your resources: + +
+
+ Content Type Options + 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. + + 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: + + Just as with the cache control element, the nosniff directive is added by default when using the <headers /> element with no child elements. + However, if you want more control over which headers are added you can use the + <content-type-options> element as shown below: + + ... + + + +]]> + The X-Content-Type-Options header is added by default with Spring Security Java configuration. If you want more control over the headers, you can + explicitly specify the content type options with the following: + +
+
+ HTTP Strict Transport Security (HSTS) + 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. + + 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): + + The optional includeSubDomains directive instructs Spring Security that subdomains (i.e. secure.mybank.example.com) should also be + treated as an HSTS domain. + As with the other headers, Spring Security adds the previous header to the response when the <headers> element is specified with + no child elements. It is also automatically added when you are using Java Configuration. You can also only use HSTS headers with the + <hsts> element as shown below: + + ... + + + +]]> + Similarly, you can enable only HSTS headers with Java Configuration: + +
+
+ X-Frame-Options + 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. + + Another modern approach to dealing with clickjacking is using a Content + Security Policy. Spring Security does not provide + support for this as the specification is not released and it is quite a bit more complicated. To stay up to date with this + issue and to see how you can implement it with Spring Security refer to + SEC-2117 + + 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: + + 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. As with the other response headers, this is automatically included when the <headers> element is specified with no + child elements. You can also explicitly specify the frame-options element to control which headers + are added to the response. + + ... + + + +]]> + Similarly, you can enable only frame options within Java Configuration with the following: + +
+
+ X-XSS-Protection + Some browsers have built in support for filtering out + reflected + XSS attacks. This is by no means full proof, 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: + + This header is included by default when the <headers> element is specified with no child elements. We can explicitly + state it using the xss-protection element as shown below: + + ... + + + +]]> + Similarly, you can enable only xss protection within Java Configuration with the following: + +
+ + diff --git a/docs/manual/src/docbook/index.xml b/docs/manual/src/docbook/index.xml index 422427d29b..dd7506b256 100644 --- a/docs/manual/src/docbook/index.xml +++ b/docs/manual/src/docbook/index.xml @@ -131,6 +131,7 @@ +