mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-02-25 00:46:42 +00:00
195 lines
6.5 KiB
Plaintext
195 lines
6.5 KiB
Plaintext
[[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[]
|
|
|
|
[[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"`
|
|
====
|
|
|
|
== 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
|
|
----
|
|
====
|
|
|
|
'''
|
|
|
|
[[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
|