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/gatewayfilter-factories/jsontogrpc-factory.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/jsontogrpc-factory.adoc index b5ce622e1..ad1a38c7d 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/jsontogrpc-factory.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/jsontogrpc-factory.adoc @@ -3,6 +3,48 @@ The JSONToGRPC GatewayFilter Factory converts a JSON payload to a gRPC request. +[[jsontogrpc-dependencies]] +== Required Dependencies + +The `JsonToGrpc` filter depends on gRPC and Protobuf libraries that are not included transitively. +You must add the following dependencies to your project: + +.pom.xml +[source,xml] +---- + + io.grpc + grpc-netty + + + io.grpc + grpc-protobuf + + + io.grpc + grpc-stub + + + com.google.protobuf + protobuf-java-util + +---- + +.build.gradle +[source,groovy] +---- +implementation 'io.grpc:grpc-netty' +implementation 'io.grpc:grpc-protobuf' +implementation 'io.grpc:grpc-stub' +implementation 'com.google.protobuf:protobuf-java-util' +---- + +The filter is only auto-configured when `io.grpc.Channel` is present on the classpath. +If the dependencies are not present, the filter will not be available and attempts to use it will fail at startup or with a `NoClassDefFoundError` at request time. + +NOTE: The gRPC and Protobuf versions are managed by the Spring Cloud Gateway BOM. +If you import `spring-cloud-dependencies` or `spring-cloud-starter-parent`, no explicit version is required. + The filter takes the following arguments: * `service`: Short name of the service that handles the request. 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.