Skip to content

Commit 0091cf6

Browse files
committed
Add RedirectToHttps Migration Doc
Issue gh-16775 Issue gh-16678
1 parent e6008b6 commit 0091cf6

File tree

1 file changed

+95
-0
lines changed
  • docs/modules/ROOT/pages/migration

1 file changed

+95
-0
lines changed

docs/modules/ROOT/pages/migration/web.adoc

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,98 @@ For example, expressions that match the JSP Servlet might use an ant pattern `/*
9090
There is not yet a general-purpose replacement for these, and so you are encouraged to use `RegexRequestMatcher`, like so: `regexMatcher("\\.jsp$")`.
9191

9292
For many applications this will make no difference since most commonly all URIs listed are matched by the default servlet.
93+
94+
[[use-redirect-to-https]]
95+
== Use RedirectToHttps Instead of Channel Security
96+
97+
Years ago, HTTPS at large was enough of a performance and configuration concern that applications wanted to be able to decide which segments of an application would require HTTPS.
98+
99+
`requires-channel` in XML and `requiresChannel` in Java Config allowed configurating an application with that in mind:
100+
101+
[tabs]
102+
======
103+
Java::
104+
+
105+
[source,java,role="primary"]
106+
----
107+
http
108+
.requiresChannel((channel) -> channel
109+
.requestMatchers("/secure/**").requiresSecureChannel()
110+
.requestMatchers("/insecure/**").requiresInsecureChannel()
111+
)
112+
----
113+
114+
Kotlin::
115+
+
116+
[source,kotlin,role="secondary"]
117+
----
118+
http {
119+
requiresChannel {
120+
secure("/secure/**")
121+
seccure("/insecure/**", "REQUIRES_INSECURE_CHANNEL")
122+
}
123+
}
124+
----
125+
126+
Xml::
127+
+
128+
[source,xml,role="secondary"]
129+
----
130+
<http>
131+
<intercept-url pattern="/secure/**" access="authenticated" requires-channel="REQUIRES_SECURE_CHANNEL"/>
132+
<intercept-url pattern="/insecure/**" access="authenticated" requires-channel="REQUIRES_INSECURE_CHANNEL"/>
133+
</http>
134+
----
135+
======
136+
137+
Modern applications should either always require HTTPS.
138+
However, there are times, like when developing locally, when one would like the application to use HTTP.
139+
Or, you may have continuing circumstances that require part of your application to be HTTP.
140+
141+
In any case, you can migrate to `redirect-to-https-request-matcher-ref` and `redirectToHttps` by first constructing a `RequestMatcher` that contains all circumstances where redirecting to HTTPS is needed.
142+
Then you can reference that request matcher like so:
143+
144+
[tabs]
145+
======
146+
Java::
147+
+
148+
[source,java,role="primary"]
149+
----
150+
http
151+
.redirectToHttps((https) -> https.requestMatchers("/secure/**"))
152+
// ...
153+
----
154+
155+
Kotlin::
156+
+
157+
[source,kotlin,role="secondary"]
158+
----
159+
var secure: RequestMatcher = PathPatternRequestMatcher.withDefaults().pattern("/secure/**")
160+
http {
161+
redirectToHttps {
162+
requestMatchers = secure
163+
}
164+
// ...
165+
}
166+
----
167+
168+
Xml::
169+
+
170+
[source,xml,role="secondary"]
171+
----
172+
<b:bean id="builder" class="org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher$Builder"/>
173+
<b:bean id="secure" class="org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher" factory-bean="builder" factory-method="matcher">
174+
<b:constructor-arg value="/secure/**"/>
175+
</b:bean>
176+
<http redirect-to-https-request-matcher-ref="secure">
177+
<intercept-url pattern="/secure/**" access="authenticated"/>
178+
<intercept-url pattern="/insecure/**" access="authenticated"/>
179+
<!-- ... -->
180+
</http>
181+
----
182+
======
183+
184+
[TIP]
185+
=====
186+
If you have several circumstances where HTTP is needed, consider using `OrRequestMatcher` to combine them into a single `RequestMatcher` instance.
187+
=====

0 commit comments

Comments
 (0)