You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
430 lines
16 KiB
430 lines
16 KiB
[[migration]] |
|
= Migrating to 6.0 |
|
|
|
The Spring Security team has prepared the 5.8 release to simplify upgrading to Spring Security 6.0. |
|
Use 5.8 and |
|
ifdef::spring-security-version[] |
|
xref:5.8.0@migration.adoc[its preparation steps] |
|
endif::[] |
|
ifndef::spring-security-version[] |
|
its preparation steps |
|
endif::[] |
|
to simplify updating to 6.0 |
|
|
|
After updating to 5.8, follow this guide to perform any needed migration steps. |
|
|
|
Also, this guide includes ways to <<revert,revert to 5.x>> behaviors and its defaults, should you run into trouble. |
|
|
|
== Servlet |
|
|
|
In Spring Security 5, the default behavior is for the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontext[`SecurityContext`] to automatically be saved to the xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] using the xref:servlet/authentication/persistence.adoc#securitycontextpersistencefilter[`SecurityContextPersistenceFilter`]. |
|
Saving must be done just prior to the `HttpServletResponse` being committed and just before `SecurityContextPersistenceFilter`. |
|
Unfortunately, automatic persistence of the `SecurityContext` can surprise users when it is done prior to the request completing (i.e. just prior to committing the `HttpServletResponse`). |
|
It also is complex to keep track of the state to determine if a save is necessary causing unnecessary writes to the `SecurityContextRepository` (i.e. `HttpSession`) at times. |
|
|
|
In Spring Security 6, the default behavior is that the xref:servlet/authentication/persistence.adoc#securitycontextholderfilter[`SecurityContextHolderFilter`] will only read the `SecurityContext` from `SecurityContextRepository` and populate it in the `SecurityContextHolder`. |
|
Users now must explicitly save the `SecurityContext` with the `SecurityContextRepository` if they want the `SecurityContext` to persist between requests. |
|
This removes ambiguity and improves performance by only requiring writing to the `SecurityContextRepository` (i.e. `HttpSession`) when it is necessary. |
|
|
|
If you are explicitly opting into Spring Security 6's new defaults, the following configuration can be removed to accept the Spring Security 6 defaults. |
|
|
|
include::partial$servlet/architecture/security-context-explicit.adoc[] |
|
|
|
=== Multiple SecurityContextRepository |
|
|
|
In Spring Security 5, the default xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] was `HttpSessionSecurityContextRepository`. |
|
|
|
In Spring Security 6, the default `SecurityContextRepository` is `DelegatingSecurityContextRepository`. |
|
If you configured the `SecurityContextRepository` only for the purpose of updating to 6.0, you can remove it completely. |
|
|
|
=== Deprecation in SecurityContextRepository |
|
|
|
There are no further migration steps for this deprecation. |
|
|
|
[[requestcache-query-optimization]] |
|
=== Optimize Querying of `RequestCache` |
|
|
|
In Spring Security 5, the default behavior is to query the xref:servlet/architecture.adoc#savedrequests[saved request] on every request. |
|
This means that in a typical setup, that in order to use the xref:servlet/architecture.adoc#requestcache[`RequestCache`] the `HttpSession` is queried on every request. |
|
|
|
In Spring Security 6, the default is that `RequestCache` will only be queried for a cached request if the HTTP parameter `continue` is defined. |
|
This allows Spring Security to avoid unnecessarily reading the `HttpSession` with the `RequestCache`. |
|
|
|
In Spring Security 5 the default is to use `HttpSessionRequestCache` which will be queried for a cached request on every request. |
|
If you are not overriding the defaults (i.e. using `NullRequestCache`), then the following configuration can be used to explicitly opt into the Spring Security 6 behavior in Spring Security 5.8: |
|
|
|
include::partial$servlet/architecture/request-cache-continue.adoc[] |
|
|
|
=== Use `AuthorizationManager` for Method Security |
|
|
|
There are no further migration steps for this feature. |
|
|
|
=== Use `AuthorizationManager` for Message Security |
|
|
|
In 6.0, `<websocket-message-broker>` defaults `use-authorization-manager` to `true`. |
|
So, to complete migration, remove any `websocket-message-broker@use-authorization-manager=true` attribute. |
|
|
|
For example: |
|
|
|
==== |
|
.Xml |
|
[source,xml,role="primary"] |
|
---- |
|
<websocket-message-broker use-authorization-manager="true"/> |
|
---- |
|
==== |
|
|
|
changes to: |
|
|
|
==== |
|
.Xml |
|
[source,xml,role="primary"] |
|
---- |
|
<websocket-message-broker/> |
|
---- |
|
==== |
|
|
|
There are no further migrations steps for Java or Kotlin for this feature. |
|
|
|
=== Use `AuthorizationManager` for Request Security |
|
|
|
In 6.0, `<http>` defaults `once-per-request` to `false`, `filter-all-dispatcher-types` to `true`, and `use-authorization-manager` to `true`. |
|
Also, xref:servlet/authorization/authorize-requests.adoc#filtersecurityinterceptor-every-request[`authorizeRequests#filterSecurityInterceptorOncePerRequest`] defaults to `false` and xref:servlet/authorization/authorize-http-requests.adoc[`authorizeHttpRequests#filterAllDispatcherTypes`] defaults to `true`. |
|
So, to complete migration, any defaults values can be removed. |
|
|
|
For example, if you opted in to the 6.0 default for `filter-all-dispatcher-types` or `authorizeHttpRequests#filterAllDispatcherTypes` like so: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
http |
|
.authorizeHttpRequests((authorize) -> authorize |
|
.filterAllDispatcherTypes(true) |
|
// ... |
|
) |
|
---- |
|
|
|
.Kotlin |
|
[source,java,role="secondary"] |
|
---- |
|
http { |
|
authorizeHttpRequests { |
|
filterAllDispatcherTypes = true |
|
// ... |
|
} |
|
} |
|
---- |
|
|
|
.Xml |
|
[source,xml,role="secondary"] |
|
---- |
|
<http use-authorization-manager="true" filter-all-dispatcher-types="true"/> |
|
---- |
|
==== |
|
|
|
then the defaults may be removed: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
http |
|
.authorizeHttpRequests((authorize) -> authorize |
|
// ... |
|
) |
|
---- |
|
|
|
.Kotlin |
|
[source,java,role="secondary"] |
|
---- |
|
http { |
|
authorizeHttpRequests { |
|
// ... |
|
} |
|
} |
|
---- |
|
|
|
.Xml |
|
[source,xml,role="secondary"] |
|
---- |
|
<http/> |
|
---- |
|
==== |
|
|
|
[NOTE] |
|
==== |
|
`once-per-request` applies only when `use-authorization-manager="false"` and `filter-all-dispatcher-types` only applies when `use-authorization-manager="true"` |
|
==== |
|
|
|
=== Propagate ``AuthenticationServiceException``s |
|
|
|
{security-api-url}org/springframework/security/web/authentication/AuthenticationFilter.html[`AuthenticationFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/authentication/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`]. |
|
Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. |
|
|
|
So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); |
|
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); |
|
handler.setRethrowAuthenticationServiceException(true); |
|
authenticationFilter.setAuthenticationFailureHandler(handler); |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) |
|
val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) |
|
handler.setRethrowAuthenticationServiceException(true) |
|
authenticationFilter.setAuthenticationFailureHandler(handler) |
|
---- |
|
|
|
.Xml |
|
[source,xml,role="secondary"] |
|
---- |
|
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter"> |
|
<!-- ... --> |
|
<property ref="authenticationFailureHandler"/> |
|
</bean> |
|
|
|
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler"> |
|
<property name="rethrowAuthenticationServiceException" value="true"/> |
|
</bean> |
|
---- |
|
==== |
|
|
|
changes to: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); |
|
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); |
|
authenticationFilter.setAuthenticationFailureHandler(handler); |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) |
|
val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) |
|
authenticationFilter.setAuthenticationFailureHandler(handler) |
|
---- |
|
|
|
.Xml |
|
[source,xml,role="secondary"] |
|
---- |
|
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter"> |
|
<!-- ... --> |
|
<property ref="authenticationFailureHandler"/> |
|
</bean> |
|
|
|
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler"> |
|
<!-- ... --> |
|
</bean> |
|
---- |
|
==== |
|
|
|
[[servlet-opt-in-sha256-rememberme]] |
|
=== Use SHA-256 in Remember Me |
|
|
|
In 6.0, the `TokenBasedRememberMeServices` uses SHA-256 to encode and match the token. |
|
To complete the migration, any default values can be removed. |
|
|
|
For example, if you opted in to the 6.0 default for `encodingAlgorithm` and `matchingAlgorithm` like so: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
@Configuration |
|
@EnableWebSecurity |
|
public class SecurityConfig { |
|
@Bean |
|
SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { |
|
http |
|
// ... |
|
.rememberMe((remember) -> remember |
|
.rememberMeServices(rememberMeServices) |
|
); |
|
return http.build(); |
|
} |
|
@Bean |
|
RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { |
|
RememberMeTokenAlgorithm encodingAlgorithm = RememberMeTokenAlgorithm.SHA256; |
|
TokenBasedRememberMeServices rememberMe = new TokenBasedRememberMeServices(myKey, userDetailsService, encodingAlgorithm); |
|
rememberMe.setMatchingAlgorithm(RememberMeTokenAlgorithm.SHA256); |
|
return rememberMe; |
|
} |
|
} |
|
---- |
|
.XML |
|
[source,xml,role="secondary"] |
|
---- |
|
<http> |
|
<remember-me services-ref="rememberMeServices"/> |
|
</http> |
|
<bean id="rememberMeServices" class= |
|
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices"> |
|
<property name="userDetailsService" ref="myUserDetailsService"/> |
|
<property name="key" value="springRocks"/> |
|
<property name="matchingAlgorithm" value="SHA256"/> |
|
<property name="encodingAlgorithm" value="SHA256"/> |
|
</bean> |
|
---- |
|
==== |
|
|
|
then the defaults can be removed: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
@Configuration |
|
@EnableWebSecurity |
|
public class SecurityConfig { |
|
@Bean |
|
SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { |
|
http |
|
// ... |
|
.rememberMe((remember) -> remember |
|
.rememberMeServices(rememberMeServices) |
|
); |
|
return http.build(); |
|
} |
|
@Bean |
|
RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { |
|
return new TokenBasedRememberMeServices(myKey, userDetailsService); |
|
} |
|
} |
|
---- |
|
.XML |
|
[source,xml,role="secondary"] |
|
---- |
|
<http> |
|
<remember-me services-ref="rememberMeServices"/> |
|
</http> |
|
<bean id="rememberMeServices" class= |
|
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices"> |
|
<property name="userDetailsService" ref="myUserDetailsService"/> |
|
<property name="key" value="springRocks"/> |
|
</bean> |
|
---- |
|
==== |
|
|
|
[[use-new-requestmatchers]] |
|
=== Use the new `requestMatchers` methods |
|
|
|
There are no further migration steps for this feature. |
|
|
|
[[use-new-security-matchers]] |
|
=== Use the new `securityMatchers` methods |
|
|
|
There are no further migration steps for this feature. |
|
|
|
=== Remove CAS support |
|
|
|
In Spring Security 6.0, the CAS support https://github.com/spring-projects/spring-security/issues/10441[has been removed]. |
|
There is no direct replacement for it, however, it is possible to https://apereo.github.io/cas/6.6.x/authentication/OAuth-Authentication.html[configure your CAS server to act as an OAuth 2.0 Authentication Provider] and use the xref::servlet/oauth2/index.adoc[OAuth 2.0 support in Spring Security]. |
|
|
|
== Reactive |
|
|
|
=== Use `AuthorizationManager` for Method Security |
|
|
|
In 6.0, `@EnableReactiveMethodSecurity` defaults `useAuthorizationManager` to `true`. |
|
So, to complete migration, {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableReactiveMethodSecurity.html[`@EnableReactiveMethodSecurity`] remove the `useAuthorizationManager` attribute: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
@EnableReactiveMethodSecurity(useAuthorizationManager = true) |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
@EnableReactiveMethodSecurity(useAuthorizationManager = true) |
|
---- |
|
==== |
|
|
|
changes to: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
@EnableReactiveMethodSecurity |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
@EnableReactiveMethodSecurity |
|
---- |
|
==== |
|
|
|
''' |
|
|
|
=== Propagate ``AuthenticationServiceException``s |
|
|
|
{security-api-url}org/springframework/security/web/server/authentication/AuthenticationWebFilter.html[`AuthenticationWebFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/web/server/ServerAuthenticationEntryPoint.html[`ServerAuthenticationEntryPoint`]. |
|
Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. |
|
|
|
So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); |
|
bearerFailureHandler.setRethrowAuthenticationServiceException(true); |
|
AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); |
|
basicFailureHandler.setRethrowAuthenticationServiceException(true); |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) |
|
bearerFailureHandler.setRethrowAuthenticationServiceException(true) |
|
val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) |
|
basicFailureHandler.setRethrowAuthenticationServiceException(true) |
|
---- |
|
==== |
|
|
|
changes to: |
|
|
|
==== |
|
.Java |
|
[source,java,role="primary"] |
|
---- |
|
AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); |
|
AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); |
|
---- |
|
|
|
.Kotlin |
|
[source,kotlin,role="secondary"] |
|
---- |
|
val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) |
|
val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) |
|
---- |
|
==== |
|
|
|
[NOTE] |
|
==== |
|
If you configured the `ServerAuthenticationFailureHandler` only for the purpose of updating to 6.0, you can remove it completely. |
|
==== |
|
|
|
[[revert]] |
|
If you are running into trouble with any of the 6.0 changes, please first try to apply the following changes to get you up and running. |
|
It's more important to stay on 6.0 and get the security improvements. |
|
|
|
== Revert Servlet |
|
|
|
== Revert Reactive
|
|
|