Extract HTTPS Documentation

Fixes gh-7626

Author: rwinch

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 <<servlet-http-redirect,Servlet>> and <<webflux-http-redirect,WebFlux>> environments.
+
+[[http-hsts]]
+== Strict Transport Security
+
+Spring Security provides support for <<headers-hsts,Strict Transport Security>> 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.

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]

docs/manual/src/docs/asciidoc/_includes/reactive/exploits/redirect-https.adoc renamed to 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 <<http,using TLS>>.
 
+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 <<servlet-headers-hsts,Strict Transport Security>> and enables it by default.
+
+[[webflux-http-proxy-server]]
+== Proxy Server Configuration
+
+Spring Security <<http-proxy-servers,integrates with proxy servers>>.

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]

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[]

docs/manual/src/docs/asciidoc/_includes/servlet/exploits/channel.adoc

@@ -0,0 +1,59 @@
+[[servlet-http]]
+= HTTP
+
+All HTTP based communication should be protected <<http,using TLS>>.
+
+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]
+----
+<http>
+	<intercept-url pattern="/**" access="ROLE_USER" requires-channel="https"/>
+...
+</http>
+----
+====
+
+
+[[servlet-hsts]]
+== Strict Transport Security
+
+Spring Security provides support for <<servlet-headers-hsts,Strict Transport Security>> and enables it by default.
+
+[[servlet-http-proxy-server]]
+== Proxy Server Configuration
+
+Spring Security <<http-proxy-servers,integrates with proxy servers>>.

docs/manual/src/docs/asciidoc/_includes/servlet/exploits/http.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]