Skip to content

Commit 021abf6

Browse files
ryanjbaxterryanjbaxter
authored
Merge pull request #4198 from won-seoop/doc-3885-spring-security-integration
GH-3885: Document Spring Security integration for WebFlux and WebMVC gateways
2 parents 191a0bb + ebc6449 commit 021abf6

3 files changed

Lines changed: 188 additions & 0 deletions

File tree

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@
5151
** xref:spring-cloud-gateway-server-webflux/global-filters.adoc[]
5252
** xref:spring-cloud-gateway-server-webflux/httpheadersfilters.adoc[]
5353
** xref:spring-cloud-gateway-server-webflux/tls-and-ssl.adoc[]
54+
** xref:spring-cloud-gateway-server-webflux/spring-security.adoc[]
5455
** xref:spring-cloud-gateway-server-webflux/http-client.adoc[]
5556
** xref:spring-cloud-gateway-server-webflux/configuration.adoc[]
5657
** xref:spring-cloud-gateway-server-webflux/route-metadata-configuration.adoc[]
@@ -116,6 +117,7 @@
116117
** xref:spring-cloud-gateway-server-webmvc/writing-custom-predicates-and-filters.adoc[]
117118
** xref:spring-cloud-gateway-server-webmvc/working-with-servlets-and-filters.adoc[]
118119
** xref:spring-cloud-gateway-server-webmvc/tls-and-ssl.adoc[]
120+
** xref:spring-cloud-gateway-server-webmvc/spring-security.adoc[]
119121
120122
// begin Gateway Proxy Exchange
121123

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
[[spring-security]]
2+
= Spring Security Integration
3+
4+
Spring Cloud Gateway Server WebFlux works with https://spring.io/projects/spring-security[Spring Security] to secure routes and relay tokens to downstream services.
5+
6+
== Dependencies
7+
8+
To add Spring Security to the gateway, include one or more of the following starters:
9+
10+
.pom.xml
11+
[source,xml]
12+
----
13+
<!-- Core security (authentication and authorization) -->
14+
<dependency>
15+
<groupId>org.springframework.boot</groupId>
16+
<artifactId>spring-boot-starter-security</artifactId>
17+
</dependency>
18+
19+
<!-- OAuth2 login and token relay to downstream services -->
20+
<dependency>
21+
<groupId>org.springframework.boot</groupId>
22+
<artifactId>spring-boot-starter-oauth2-client</artifactId>
23+
</dependency>
24+
25+
<!-- Resource server: validate JWT or opaque tokens on each request -->
26+
<dependency>
27+
<groupId>org.springframework.boot</groupId>
28+
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
29+
</dependency>
30+
----
31+
32+
== Default Behavior
33+
34+
When `spring-boot-starter-security` is on the classpath, Spring Boot auto-configures a `SecurityWebFilterChain` that requires *all* requests to be authenticated.
35+
You must provide an explicit `SecurityWebFilterChain` bean to open up specific paths or apply custom rules.
36+
37+
The following example allows health-check endpoints without authentication and requires a valid JWT on all other requests:
38+
39+
.RouteSecurityConfiguration.java
40+
[source,java]
41+
----
42+
import org.springframework.context.annotation.Bean;
43+
import org.springframework.context.annotation.Configuration;
44+
import org.springframework.security.config.Customizer;
45+
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
46+
import org.springframework.security.config.web.server.ServerHttpSecurity;
47+
import org.springframework.security.web.server.SecurityWebFilterChain;
48+
49+
@Configuration
50+
@EnableWebFluxSecurity
51+
public class RouteSecurityConfiguration {
52+
53+
@Bean
54+
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
55+
return http
56+
.authorizeExchange(exchanges -> exchanges
57+
.pathMatchers("/actuator/health/**").permitAll()
58+
.anyExchange().authenticated())
59+
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
60+
.build();
61+
}
62+
}
63+
----
64+
65+
== Token Relay
66+
67+
When the gateway acts as an OAuth2 client, it can forward the currently authenticated user's access token to downstream services.
68+
See the xref:spring-cloud-gateway-server-webflux/gatewayfilter-factories/tokenrelay-factory.adoc[TokenRelay GatewayFilter Factory] documentation for usage and required dependencies.
69+
70+
== Further Reading
71+
72+
See the https://docs.spring.io/spring-security/reference/reactive/index.html[Spring Security Reactive Web Applications] reference for full details on `SecurityWebFilterChain`, method security, and OAuth2 integration.

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
[[spring-security]]
2+
= Spring Security Integration
3+
4+
Spring Cloud Gateway Server MVC works with https://spring.io/projects/spring-security[Spring Security] to secure routes and relay tokens to downstream services.
5+
6+
== Dependencies
7+
8+
To add Spring Security to the gateway, include one or more of the following starters:
9+
10+
.pom.xml
11+
[source,xml]
12+
----
13+
<!-- Core security (authentication and authorization) -->
14+
<dependency>
15+
<groupId>org.springframework.boot</groupId>
16+
<artifactId>spring-boot-starter-security</artifactId>
17+
</dependency>
18+
19+
<!-- OAuth2 login and token relay to downstream services -->
20+
<dependency>
21+
<groupId>org.springframework.boot</groupId>
22+
<artifactId>spring-boot-starter-oauth2-client</artifactId>
23+
</dependency>
24+
25+
<!-- Resource server: validate JWT or opaque tokens on each request -->
26+
<dependency>
27+
<groupId>org.springframework.boot</groupId>
28+
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
29+
</dependency>
30+
----
31+
32+
== Default Behavior
33+
34+
When `spring-boot-starter-security` is on the classpath, Spring Boot auto-configures a `SecurityFilterChain` that requires *all* requests to be authenticated.
35+
Provide an explicit `SecurityFilterChain` bean to customize access rules for your gateway routes.
36+
37+
The following example allows health-check endpoints without authentication and requires a valid JWT on all other requests:
38+
39+
.RouteSecurityConfiguration.java
40+
[source,java]
41+
----
42+
import org.springframework.context.annotation.Bean;
43+
import org.springframework.context.annotation.Configuration;
44+
import org.springframework.security.config.Customizer;
45+
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
46+
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
47+
import org.springframework.security.web.SecurityFilterChain;
48+
49+
@Configuration
50+
@EnableWebSecurity
51+
public class RouteSecurityConfiguration {
52+
53+
@Bean
54+
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
55+
http
56+
.authorizeHttpRequests(authorize -> authorize
57+
.requestMatchers("/actuator/health/**").permitAll()
58+
.anyRequest().authenticated())
59+
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
60+
return http.build();
61+
}
62+
}
63+
----
64+
65+
[[spring-security-http-firewall]]
66+
== HTTP Firewall
67+
68+
Spring Security includes a `StrictHttpFirewall` that rejects HTTP requests whose URLs contain certain characters — such as encoded path separators (`%2F`), double forward slashes (`//`), or backslashes.
69+
These patterns can be legitimate in a gateway that proxies requests to downstream services that accept such paths.
70+
71+
If the gateway is rejecting requests with a `400 Bad Request` before any route is matched, the `StrictHttpFirewall` may be blocking them.
72+
You can relax it as follows:
73+
74+
.RouteSecurityConfiguration.java
75+
[source,java]
76+
----
77+
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;
78+
import org.springframework.security.web.firewall.HttpFirewall;
79+
import org.springframework.security.web.firewall.StrictHttpFirewall;
80+
81+
@Configuration
82+
@EnableWebSecurity
83+
public class RouteSecurityConfiguration {
84+
85+
@Bean
86+
public HttpFirewall relaxedHttpFirewall() {
87+
StrictHttpFirewall firewall = new StrictHttpFirewall();
88+
firewall.setAllowUrlEncodedSlash(true); // allow %2F in path
89+
firewall.setAllowUrlEncodedDoubleSlash(true); // allow %2F%2F
90+
firewall.setAllowBackSlash(true); // allow \ in path
91+
return firewall;
92+
}
93+
94+
@Bean
95+
public WebSecurityCustomizer webSecurityCustomizer() {
96+
return web -> web.httpFirewall(relaxedHttpFirewall());
97+
}
98+
}
99+
----
100+
101+
[CAUTION]
102+
====
103+
Only relax the `StrictHttpFirewall` when your downstream services explicitly require it and your threat model accounts for the implications.
104+
See the https://docs.spring.io/spring-security/reference/servlet/exploits/firewall.html[Spring Security HTTP Firewall] reference for details.
105+
====
106+
107+
== Token Relay
108+
109+
When the gateway acts as an OAuth2 client, it can forward the currently authenticated user's access token to downstream services.
110+
See the xref:spring-cloud-gateway-server-webmvc/filters/tokenrelay.adoc[TokenRelay filter] documentation for usage and required dependencies.
111+
112+
== Further Reading
113+
114+
See the https://docs.spring.io/spring-security/reference/servlet/index.html[Spring Security Servlet Applications] reference for full details on `SecurityFilterChain`, method security, and OAuth2 integration.

0 commit comments

Comments
 (0)