From b3d177fc7e8d3c0f94ccca48834e9462589e2142 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Mon, 25 Nov 2019 15:49:51 -0600 Subject: [PATCH] Extract HTTPS Documentation Fixes gh-7626 --- .../_includes/about/exploits/http.adoc | 32 ++++++++++ .../_includes/about/exploits/index.adoc | 2 + .../{redirect-https.adoc => http.adoc} | 32 ++++++++-- .../_includes/reactive/exploits/index.adoc | 2 +- .../_includes/servlet/appendix/index.adoc | 2 - .../_includes/servlet/exploits/channel.adoc | 33 ----------- .../_includes/servlet/exploits/http.adoc | 59 +++++++++++++++++++ .../_includes/servlet/exploits/index.adoc | 2 +- 8 files changed, 123 insertions(+), 41 deletions(-) create mode 100644 docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc rename docs/manual/src/docs/asciidoc/_includes/reactive/exploits/{redirect-https.adoc => http.adoc} (50%) delete mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/exploits/channel.adoc create mode 100644 docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc b/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc new file mode 100644 index 0000000000..5d0dfa6c32 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc @@ -0,0 +1,32 @@ +[[http]] += HTTP + +All HTTP based communication, including https://www.troyhunt.com/heres-why-your-static-website-needs-https/[static resources], should be protected https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html[using TLS]. + +As a framework, Spring Security does not handle HTTP connections and thus does not provide support for HTTPS directly. +However, it does provide a number of features that help with HTTPS usage. + +[[http-redirect]] +== Redirect to HTTPS + +When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both <> and <> environments. + +[[http-hsts]] +== Strict Transport Security + +Spring Security provides support for <> and enables it by default. + +[[http-proxy-server]] +== Proxy Server Configuration + +When using a proxy server it is important to ensure that you have configured your application properly. +For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080 +Without proper configuration, the application server will not know that the load balancer exists and treat the request as though https://192.168.1:8080 was requested by the client. + +To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used. +To make the application aware of this, you need to either configure your application server aware of the X-Forwarded headers. +For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer]. +Alternatively, Spring users can leverage https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[ForwardedHeaderFilter]. + +Spring Boot users may use the `server.use-forward-headers` property to configure the application. +See the https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-use-tomcat-behind-a-proxy-server[Spring Boot documentation] for further details. diff --git a/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc b/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc index bb42a5c6dc..bb8abc73dc 100644 --- a/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc @@ -8,3 +8,5 @@ Below you will find high level description of the various exploits that Spring S include::csrf.adoc[leveloffset=+1] include::headers.adoc[leveloffset=+1] + +include::http.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/redirect-https.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc similarity index 50% rename from docs/manual/src/docs/asciidoc/_includes/reactive/exploits/redirect-https.adoc rename to docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc index 755daac20e..fbcb56383c 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/redirect-https.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/http.adoc @@ -1,9 +1,19 @@ -[[webflux-redirect-https]] -= Redirect to HTTPS +[[webflux-http]] += HTTP -HTTPS is required to provide a secure application. -Spring Security can be configured to perform a redirect to https using the following Java Configuration: +All HTTP based communication should be protected <>. +Below you can find details around WebFlux specific features that assist with HTTPS usage. + +[[webflux-http-redirect]] +== Redirect to HTTPS + +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: + +.Redirect to HTTPS +==== [source,java] ---- @Bean @@ -14,11 +24,14 @@ SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { 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: +.Redirect to HTTPS when X-Forwarded +==== [source,java] ---- @Bean @@ -32,3 +45,14 @@ SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { return http.build(); } ---- +==== + +[[webflux-hsts]] +== Strict Transport Security + +Spring Security provides support for <> and enables it by default. + +[[webflux-http-proxy-server]] +== Proxy Server Configuration + +Spring Security <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc index 396bc8ffc5..6d5c8c66a8 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/exploits/index.adoc @@ -4,4 +4,4 @@ include::csrf.adoc[leveloffset=+1] include::headers.adoc[leveloffset=+1] -include::redirect-https.adoc[leveloffset=+1] +include::http.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc index 9c711172b8..f0a169ecfb 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/appendix/index.adoc @@ -7,6 +7,4 @@ include::namespace.adoc[] include::dependencies.adoc[] -include::proxy-server.adoc[] - include::faq.adoc[] diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/channel.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/channel.adoc deleted file mode 100644 index fb1afcf421..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/channel.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[[ns-requires-channel]] -= HTTPS - -== Adding HTTP/HTTPS Channel Security -If your application supports both HTTP and HTTPS, and you require that particular URLs can only be accessed over HTTPS, then this is directly supported using the `requires-channel` attribute on ``: - -[source,xml] ----- - - - -... - ----- - -With this configuration in place, if a user attempts to access anything matching the "/secure/**" pattern using HTTP, they will first be redirected to an HTTPS URL footnote:[For more details on how channel-processing is implemented, see the Javadoc for `ChannelProcessingFilter` and related classes.]. -The available options are "http", "https" or "any". -Using the value "any" means that either HTTP or HTTPS can be used. - -If your application uses non-standard ports for HTTP and/or HTTPS, you can specify a list of port mappings as follows: - -[source,xml] ----- - -... - - - - ----- - -Note that in order to be truly secure, an application should not use HTTP at all or switch between HTTP and HTTPS. -It should start in HTTPS (with the user entering an HTTPS URL) and use a secure connection throughout to avoid any possibility of man-in-the-middle attacks. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc new file mode 100644 index 0000000000..18593d83e3 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.adoc @@ -0,0 +1,59 @@ +[[servlet-http]] += HTTP + +All HTTP based communication should be protected <>. + +Below you can find details around Servlet specific features that assist with HTTPS usage. + +[[servlet-http-redirect]] +== Redirect to HTTPS + +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: + +.Redirect to HTTPS with Java Configuration +==== +[source,java] +---- +@Configuration +@EnableWebSecurity +public class WebSecurityConfig extends + WebSecurityConfigurerAdapter { + + @Override + protected void configure(HttpSecurity http) { + http + // ... + .requiresChannel(channel -> + channel + .anyRequest().requiresSecure() + ); + } +} +---- +==== + +The following XML configuration will redirect all HTTP requests to HTTPS + +.Redirect to HTTPS with XML Configuration +==== +[source,xml] +---- + + +... + +---- +==== + + +[[servlet-hsts]] +== Strict Transport Security + +Spring Security provides support for <> and enables it by default. + +[[servlet-http-proxy-server]] +== Proxy Server Configuration + +Spring Security <>. diff --git a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc index f6aee0b1b3..6d5c8c66a8 100644 --- a/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/servlet/exploits/index.adoc @@ -4,4 +4,4 @@ include::csrf.adoc[leveloffset=+1] include::headers.adoc[leveloffset=+1] -include::channel.adoc[leveloffset=+1] +include::http.adoc[leveloffset=+1]