diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 58d9ea694..04f93b27a 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/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 diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/spring-security.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/spring-security.adoc new file mode 100644 index 000000000..c9fc7c1d6 --- /dev/null +++ b/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] +---- + + org.springframework.boot + spring-boot-starter-security + +---- + +.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. diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/spring-security.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/spring-security.adoc new file mode 100644 index 000000000..0200e74e1 --- /dev/null +++ b/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] +---- + + org.springframework.boot + spring-boot-starter-security + +---- + +.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.