GH-3885: Add documentation for Spring Security integration

docs/modules/ROOT/nav.adoc

@@ -59,6 +59,7 @@
 ** xref:spring-cloud-gateway-server-webflux/the-discoveryclient-route-definition-locator.adoc[]
 ** xref:spring-cloud-gateway-server-webflux/reactor-netty-access-logs.adoc[]
 ** xref:spring-cloud-gateway-server-webflux/cors-configuration.adoc[]
+** xref:spring-cloud-gateway-server-webflux/spring-security.adoc[]
 ** xref:spring-cloud-gateway-server-webflux/actuator-api.adoc[]
 ** xref:spring-cloud-gateway-server-webflux/sharing-routes.adoc[]
 ** xref:spring-cloud-gateway-server-webflux/troubleshooting.adoc[]
@@ -114,6 +115,7 @@
 ** xref:spring-cloud-gateway-server-webmvc/httpheadersfilters.adoc[]
 ** xref:spring-cloud-gateway-server-webmvc/writing-custom-predicates-and-filters.adoc[]
 ** xref:spring-cloud-gateway-server-webmvc/working-with-servlets-and-filters.adoc[]
+** xref:spring-cloud-gateway-server-webmvc/spring-security.adoc[]
 ** xref:spring-cloud-gateway-server-webmvc/tls-and-ssl.adoc[]
 
 // begin Gateway Proxy Exchange

docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/spring-security.adoc

@@ -0,0 +1,81 @@
+[[spring-security]]
+= Spring Security Integration
+
+Spring Cloud Gateway Server WebFlux can integrate with https://spring.io/projects/spring-security[Spring Security] to add authentication, authorization, and other security features to your gateway.
+
+[[spring-security-dependencies]]
+== Including Spring Security
+
+To include Spring Security in your Spring Cloud Gateway Server WebFlux project, add the following dependency:
+
+.pom.xml
+[source,xml]
+----
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-security</artifactId>
+</dependency>
+----
+
+.build.gradle
+[source,groovy]
+----
+implementation 'org.springframework.boot:spring-boot-starter-security'
+----
+
+Once Spring Security is on the classpath, a default `SecurityWebFilterChain` bean is auto-configured that denies all requests unless explicitly permitted.
+You must configure your own `SecurityWebFilterChain` bean to specify your desired security rules.
+See the https://docs.spring.io/spring-security/reference/reactive/configuration/webflux.html[Spring Security WebFlux documentation] for details.
+
+[[spring-security-firewall]]
+== HTTP Firewall
+
+When Spring Security is included, a `ServerWebExchangeFirewall` is applied to all incoming requests.
+By default, Spring Security configures a `StrictServerWebExchangeFirewall`, which rejects requests that contain potentially dangerous patterns in the URL, such as:
+
+* URL-encoded characters (e.g., `%2F` for `/`)
+* Semi-colon characters
+* Normalized path traversal sequences
+
+Because Spring Cloud Gateway acts as a reverse proxy, legitimate downstream requests may contain URL patterns that the default firewall rejects.
+For example, when using the xref:spring-cloud-gateway-server-webflux/request-predicates-factories.adoc[`Path` predicate], URL-encoded characters in the path must be allowed through the firewall.
+
+To relax the firewall rules, configure a custom `StrictServerWebExchangeFirewall` bean:
+
+.SecurityConfiguration.java
+[source,java]
+----
+@Configuration
+@EnableWebFluxSecurity
+public class SecurityConfiguration {
+
+    @Bean
+    public StrictServerWebExchangeFirewall httpFirewall() {
+        StrictServerWebExchangeFirewall firewall = new StrictServerWebExchangeFirewall();
+        firewall.setAllowUrlEncodedPercent(true);
+        firewall.setAllowUrlEncodedSlash(true);
+        return firewall;
+    }
+
+    @Bean
+    public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http,
+            StrictServerWebExchangeFirewall firewall) {
+        return http
+                .httpFirewall(firewall)
+                .authorizeExchange(exchanges -> exchanges
+                        .anyExchange().authenticated())
+                .build();
+    }
+}
+----
+
+NOTE: Be cautious when relaxing firewall restrictions.
+Only allow URL-encoded characters that are required for your specific routing rules.
+Overly permissive firewall settings may expose your application to security vulnerabilities.
+See the https://docs.spring.io/spring-security/reference/servlet/exploits/firewall.html[Spring Security HTTP Firewall documentation] for a complete reference.
+
+[[spring-security-oauth2]]
+== OAuth2 and Token Relay
+
+Spring Cloud Gateway Server WebFlux supports OAuth2 login and token relay to downstream services.
+See the xref:spring-cloud-gateway-server-webflux/gatewayfilter-factories/tokenrelay-factory.adoc[`TokenRelay` `GatewayFilter` Factory] documentation for details.

docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/spring-security.adoc

@@ -0,0 +1,88 @@
+[[spring-security]]
+= Spring Security Integration
+
+Spring Cloud Gateway Server MVC can integrate with https://spring.io/projects/spring-security[Spring Security] to add authentication, authorization, and other security features to your gateway.
+
+[[spring-security-dependencies]]
+== Including Spring Security
+
+To include Spring Security in your Spring Cloud Gateway Server MVC project, add the following dependency:
+
+.pom.xml
+[source,xml]
+----
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-security</artifactId>
+</dependency>
+----
+
+.build.gradle
+[source,groovy]
+----
+implementation 'org.springframework.boot:spring-boot-starter-security'
+----
+
+Once Spring Security is on the classpath, a default `SecurityFilterChain` bean is auto-configured that denies all requests unless explicitly permitted.
+You must configure your own `SecurityFilterChain` bean to specify your desired security rules.
+See the https://docs.spring.io/spring-security/reference/servlet/configuration/java.html[Spring Security Servlet documentation] for details.
+
+[[spring-security-firewall]]
+== HTTP Firewall
+
+When Spring Security is included, an `HttpFirewall` is applied to all incoming requests.
+By default, Spring Security configures a `StrictHttpFirewall`, which rejects requests that contain potentially dangerous patterns in the URL, such as:
+
+* URL-encoded characters (e.g., `%2F` for `/`)
+* Semi-colon characters
+* Normalized path traversal sequences
+
+Because Spring Cloud Gateway acts as a reverse proxy, legitimate downstream requests may contain URL patterns that the default firewall rejects.
+For example, when proxying requests whose paths include URL-encoded characters, you must relax the corresponding firewall restrictions.
+
+To customize the firewall rules, configure a custom `StrictHttpFirewall` bean:
+
+.SecurityConfiguration.java
+[source,java]
+----
+@Configuration
+@EnableWebSecurity
+public class SecurityConfiguration {
+
+    @Bean
+    public StrictHttpFirewall httpFirewall() {
+        StrictHttpFirewall firewall = new StrictHttpFirewall();
+        firewall.setAllowUrlEncodedPercent(true);
+        firewall.setAllowUrlEncodedSlash(true);
+        return firewall;
+    }
+
+    @Bean
+    public SecurityFilterChain springSecurityFilterChain(HttpSecurity http) throws Exception {
+        return http
+                .authorizeHttpRequests(authorize -> authorize
+                        .anyRequest().authenticated())
+                .build();
+    }
+}
+----
+
+NOTE: Be cautious when relaxing firewall restrictions.
+Only allow URL-encoded characters that are required for your specific routing rules.
+Overly permissive firewall settings may expose your application to security vulnerabilities.
+See the https://docs.spring.io/spring-security/reference/servlet/exploits/firewall.html[Spring Security HTTP Firewall documentation] for a complete reference.
+
+[[spring-security-filter-ordering]]
+== Filter Ordering with Spring Security
+
+Spring Cloud Gateway Server MVC relies on Spring MVC's `DispatcherServlet` and servlet filters.
+When using Spring Security, the `SecurityFilterChain` is applied via a `DelegatingFilterProxy` registered at `Ordered.HIGHEST_PRECEDENCE`.
+If you have custom gateway filters or servlet filters, ensure they are ordered correctly relative to Spring Security's filter chain.
+
+See xref:spring-cloud-gateway-server-webmvc/working-with-servlets-and-filters.adoc[Working with Servlets and Servlet Filters] for details on filter ordering.
+
+[[spring-security-oauth2]]
+== OAuth2 and Token Relay
+
+Spring Cloud Gateway Server MVC supports OAuth2 login and token relay to downstream services.
+See the xref:spring-cloud-gateway-server-webmvc/filters/tokenrelay.adoc[`TokenRelay` Filter] documentation for details.