476 lines
13 KiB
Plaintext
476 lines
13 KiB
Plaintext
= Web Migrations
|
|
|
|
== Favor Relative URIs
|
|
|
|
When redirecting to a login endpoint, Spring Security has favored absolute URIs in the past.
|
|
For example, if you set your login page like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
http
|
|
// ...
|
|
.formLogin((form) -> form.loginPage("/my-login"))
|
|
// ...
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
http {
|
|
formLogin {
|
|
loginPage = "/my-login"
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
<http ...>
|
|
<form-login login-page="/my-login"/>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
then when redirecting to `/my-login` Spring Security would use a `Location:` like the following:
|
|
|
|
[source]
|
|
----
|
|
302 Found
|
|
// ...
|
|
Location: https://myapp.example.org/my-login
|
|
----
|
|
|
|
However, this is no longer necessary given that the RFC is was based on is now obsolete.
|
|
|
|
In Spring Security 7, this is changed to use a relative URI like so:
|
|
|
|
[source]
|
|
----
|
|
302 Found
|
|
// ...
|
|
Location: /my-login
|
|
----
|
|
|
|
Most applications will not notice a difference.
|
|
However, in the event that this change causes problems, you can switch back to the Spring Security 6 behavior by setting the `favorRelativeUrls` value:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
LoginUrlAuthenticationEntryPoint entryPoint = new LoginUrlAuthenticationEntryPoint("/my-login");
|
|
entryPoint.setFavorRelativeUris(false);
|
|
http
|
|
// ...
|
|
.exceptionHandling((exceptions) -> exceptions.authenticaitonEntryPoint(entryPoint))
|
|
// ...
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
LoginUrlAuthenticationEntryPoint entryPoint = LoginUrlAuthenticationEntryPoint("/my-login")
|
|
entryPoint.setFavorRelativeUris(false)
|
|
|
|
http {
|
|
exceptionHandling {
|
|
authenticationEntryPoint = entryPoint
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http entry-point-ref="myEntryPoint">
|
|
<!-- ... -->
|
|
</http>
|
|
|
|
<b:bean id="myEntryPoint" class="org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint">
|
|
<b:property name="favorRelativeUris" value="true"/>
|
|
</b:bean>
|
|
----
|
|
======
|
|
|
|
== PortResolver
|
|
|
|
Spring Security uses an API called `PortResolver` to provide a workaround for a bug in Internet Explorer.
|
|
The workaround is no longer necessary and can cause users problems in some scenarios.
|
|
For this reason, Spring Security 7 will remove the `PortResolver` interface.
|
|
|
|
To prepare for this change, users should expose the `PortResolver.NO_OP` as a Bean named `portResolver`.
|
|
This ensures that the `PortResolver` implementation that is used is a no-op (e.g. does nothing) which simulates the removal of `PortResolver`.
|
|
An example configuration can be found below:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
PortResolver portResolver() {
|
|
return PortResolver.NO_OP;
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
open fun portResolver(): PortResolver {
|
|
return PortResolver.NO_OP
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
|
|
<util:constant id="portResolver"
|
|
static-field="org.springframework.security.web.PortResolver.NO_OP">
|
|
----
|
|
======
|
|
|
|
[[use-path-pattern]]
|
|
== Use PathPatternRequestMatcher by Default
|
|
|
|
In Spring Security 7, `AntPathRequestMatcher` and `MvcRequestMatcher` are no longer supported and the Java DSL requires that all URIs be absolute (less any context root).
|
|
At that time, Spring Security 7 will use `PathPatternRequestMatcher` by default.
|
|
|
|
To check how prepared you are for this change, you can publish this bean:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
PathPatternRequestMatcherBuilderFactoryBean requestMatcherBuilder() {
|
|
return new PathPatternRequestMatcherBuilderFactoryBean();
|
|
}
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
fun requestMatcherBuilder(): PathPatternRequestMatcherBuilderFactoryBean {
|
|
return PathPatternRequestMatcherBuilderFactoryBean()
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<b:bean class="org.springframework.security.config.web.PathPatternRequestMatcherBuilderFactoryBean"/>
|
|
----
|
|
======
|
|
|
|
This will tell the Spring Security DSL to use `PathPatternRequestMatcher` for all request matchers that it constructs.
|
|
|
|
In the event that you are directly constructing an object (as opposed to having the DSL construct it) that has a `setRequestMatcher` method. you should also proactively specify a `PathPatternRequestMatcher` there as well.
|
|
|
|
=== Migrate `exitUserUrl` and `switchUserUrl` Request Matchers in `SwitchUserFilter`
|
|
|
|
`SwitchUserFilter`, constructs an `AntPathRequestMatcher` in its `setExitUserUrl` and `setSwitchUserUrl` methods.
|
|
This will change to use `PathPatternRequestMatcher` in Spring Security 7.
|
|
|
|
To prepare for this change, call `setExitUserMatcher` and `setSwithcUserMatcher` to provide this `PathPatternRequestMatcher` in advance.
|
|
That is, change this:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
SwitchUserFilter switchUser = new SwitchUserFilter();
|
|
// ... other configuration
|
|
switchUser.setExitUserUrl("/exit/impersonate");
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val switchUser = SwitchUserFilter()
|
|
// ... other configuration
|
|
switchUser.setExitUserUrl("/exit/impersonate")
|
|
----
|
|
======
|
|
|
|
to this:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
SwitchUserFilter switchUser = new SwitchUserFilter();
|
|
// ... other configuration
|
|
switchUser.setExitUserMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/exit/impersonate"));
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val switchUser = SwitchUserFilter()
|
|
// ... other configuration
|
|
switchUser.setExitUserMatcher(PathPatternRequestMatcher.withDefaults().matcher(HttpMethod.POST, "/exit/impersonate"))
|
|
----
|
|
======
|
|
|
|
=== Migrate `filterProcessingUrl` Request Matcher in `AbstractAuthenticationProcessingFilter` Implementations
|
|
|
|
Spring Security 6 converts any processing endpoint configured through `setFilterProcessingUrl` to an `AntPathRequestMatcher`.
|
|
In Spring Security 7, this will change to `PathPatternRequestMatcher`.
|
|
|
|
If you are directly invoking `setFilterProcessingUrl` on a filter that extends `AbstractAuthenticationProcessingFilter`, like `UsernamePasswordAuthenticationFilter`, `OAuth2LoginAuthenticationFilter`, `Saml2WebSsoAuthenticationFilter`, `OneTimeTokenAuthenticationFilter`, or `WebAuthnAuthenticationFilter`, call `setRequiredAuthenticationRequestMatcher` instead to provide this `PathPatternRequestMatcher` in advance.
|
|
|
|
That is, change this:
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
UsernamePasswordAuthenticationFilter usernamePassword = new UsernamePasswordAuthenticationFilter(authenticationManager);
|
|
usernamePassword.setFilterProcessingUrl("/my/processing/url");
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val usernamePassword = UsernamePasswordAuthenticationFilter(authenticationManager)
|
|
usernamePassword.setFilterProcessingUrl("/my/processing/url")
|
|
----
|
|
======
|
|
|
|
to this:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
UsernamePasswordAuthenticationFilter usernamePassword = new UsernamePasswordAuthenticationFilter(authenticationManager);
|
|
RequestMatcher requestMatcher = PathPatternRequestMatcher.withDefaults().matcher("/my/processing/url");
|
|
usernamePassword.setRequest(requestMatcher);
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val usernamePassword = UsernamePasswordAuthenticationFilter(authenticationManager)
|
|
val requestMatcher = PathPatternRequestMatcher.withDefaults().matcher("/my/processing/url")
|
|
usernamePassword.setRequest(requestMatcher)
|
|
----
|
|
======
|
|
|
|
[NOTE]
|
|
-----
|
|
Most applications use the DSL instead of setting the `filterProcessingUrl` directly on a filter instance.
|
|
-----
|
|
|
|
=== Migrate CAS Proxy Receptor Request Matcher
|
|
|
|
Spring Security 6 converts any configured `proxyReceptorUrl` to a request matcher that matches the end of the request, that is `/**/proxy/receptor`.
|
|
In Spring Security 7, this pattern is not allowed and will change to using `PathPatternRequestMatcher`.
|
|
Also in Spring Security 7m the URL should by absolute, excluding any context path, like so: `/proxy/receptor`.
|
|
|
|
So to prepare for these change, you can use `setProxyReceptorRequestMatcher` instead of `setProxyReceptorUrl`.
|
|
|
|
That is, change this:
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
casAuthentication.setProxyReceptorUrl("/proxy/receptor");
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
casAuthentication.setProxyReceptorUrl("/proxy/receptor")
|
|
----
|
|
======
|
|
|
|
to this:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
casAuthentication.setProxyReceptorUrl(PathPatternRequestMatcher.withDefaults().matcher("/proxy/receptor"));
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
casAuthentication.setProxyReceptorUrl(PathPatternRequestMatcher.withDefaults().matcher("/proxy/receptor"))
|
|
----
|
|
======
|
|
|
|
== Include the Servlet Path Prefix in Authorization Rules
|
|
|
|
For many applications <<use-path-pattern, the above>> will make no difference since most commonly all URIs listed are matched by the default servlet.
|
|
|
|
However, if you have other servlets with servlet path prefixes, xref:servlet/authorization/authorize-http-requests.adoc[then these paths now need to be supplied separately].
|
|
|
|
For example, if I have a Spring MVC controller with `@RequestMapping("/orders")` and my MVC application is deployed to `/mvc` (instead of the default servlet), then the URI for this endpoint is `/mvc/orders`.
|
|
Historically, the Java DSL hasn't had a simple way to specify the servlet path prefix and Spring Security attempted to infer it.
|
|
|
|
Over time, we learned that these inference would surprise developers.
|
|
Instead of taking this responsibility away from developers, now it is simpler to specify the servlet path prefix like so:
|
|
|
|
[method,java]
|
|
----
|
|
PathPatternRequestParser.Builder servlet = PathPatternRequestParser.servletPath("/mvc");
|
|
http
|
|
.authorizeHttpRequests((authorize) -> authorize
|
|
.requestMatchers(servlet.pattern("/orders/**").matcher()).authenticated()
|
|
)
|
|
----
|
|
|
|
|
|
For paths that belong to the default servlet, use `PathPatternRequestParser.path()` instead:
|
|
|
|
[method,java]
|
|
----
|
|
PathPatternRequestParser.Builder request = PathPatternRequestParser.path();
|
|
http
|
|
.authorizeHttpRequests((authorize) -> authorize
|
|
.requestMatchers(request.pattern("/js/**").matcher()).authenticated()
|
|
)
|
|
----
|
|
|
|
Note that this doesn't address every kind of servlet since not all servlets have a path prefix.
|
|
For example, expressions that match the JSP Servlet might use an ant pattern `/**/*.jsp`.
|
|
|
|
There is not yet a general-purpose replacement for these, and so you are encouraged to use `RegexRequestMatcher`, like so: `regexMatcher("\\.jsp$")`.
|
|
|
|
For many applications this will make no difference since most commonly all URIs listed are matched by the default servlet.
|
|
|
|
[[use-redirect-to-https]]
|
|
== Use RedirectToHttps Instead of Channel Security
|
|
|
|
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.
|
|
|
|
`requires-channel` in XML and `requiresChannel` in Java Config allowed configurating an application with that in mind:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
http
|
|
.requiresChannel((channel) -> channel
|
|
.requestMatchers("/secure/**").requiresSecureChannel()
|
|
.requestMatchers("/insecure/**").requiresInsecureChannel()
|
|
)
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
http {
|
|
requiresChannel {
|
|
secure("/secure/**")
|
|
seccure("/insecure/**", "REQUIRES_INSECURE_CHANNEL")
|
|
}
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<intercept-url pattern="/secure/**" access="authenticated" requires-channel="REQUIRES_SECURE_CHANNEL"/>
|
|
<intercept-url pattern="/insecure/**" access="authenticated" requires-channel="REQUIRES_INSECURE_CHANNEL"/>
|
|
</http>
|
|
----
|
|
======
|
|
|
|
Modern applications should either always require HTTPS.
|
|
However, there are times, like when developing locally, when one would like the application to use HTTP.
|
|
Or, you may have continuing circumstances that require part of your application to be HTTP.
|
|
|
|
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.
|
|
Then you can reference that request matcher like so:
|
|
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
http
|
|
.redirectToHttps((https) -> https.requestMatchers("/secure/**"))
|
|
// ...
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
var secure: RequestMatcher = PathPatternRequestMatcher.withDefaults().pattern("/secure/**")
|
|
http {
|
|
redirectToHttps {
|
|
requestMatchers = secure
|
|
}
|
|
// ...
|
|
}
|
|
----
|
|
|
|
Xml::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<b:bean id="builder" class="org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher$Builder"/>
|
|
<b:bean id="secure" class="org.springframework.security.web.servlet.util.matcher.PathPatternRequestMatcher" factory-bean="builder" factory-method="matcher">
|
|
<b:constructor-arg value="/secure/**"/>
|
|
</b:bean>
|
|
<http redirect-to-https-request-matcher-ref="secure">
|
|
<intercept-url pattern="/secure/**" access="authenticated"/>
|
|
<intercept-url pattern="/insecure/**" access="authenticated"/>
|
|
<!-- ... -->
|
|
</http>
|
|
----
|
|
======
|
|
|
|
[TIP]
|
|
=====
|
|
If you have several circumstances where HTTP is needed, consider using `OrRequestMatcher` to combine them into a single `RequestMatcher` instance.
|
|
=====
|