spring-security/docs/modules/ROOT/pages/migration.adoc

209 lines
5.8 KiB
Plaintext
Raw Normal View History

2022-10-25 07:38:58 +08:00
[[migration]]
= Migrating to 6.0
The Spring Security team has prepared the 5.8 release to simplify upgrading to Spring Security 6.0.
2022-10-26 05:04:43 +08:00
Use 5.8 and its preparation steps to simplify updating to 6.0
2022-10-25 07:38:58 +08:00
2022-10-26 05:04:43 +08:00
After updating to 5.8, follow this guide to perform any needed migration steps.
2022-10-25 07:38:58 +08:00
2022-10-27 02:52:37 +08:00
Also, this guide includes ways to <<revert,revert to 5.x>> behaviors and its defaults, should you run into trouble.
2022-10-25 07:38:58 +08:00
2022-10-27 02:52:37 +08:00
== Servlet
2022-10-25 07:38:58 +08:00
[[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[]
2022-10-27 02:52:37 +08:00
=== Use `AuthorizationManager` for Method Security
2022-10-25 07:38:58 +08:00
2022-10-27 02:52:37 +08:00
There are no further migration steps for this feature.
However, if you run into trouble with this enhancement, you can instead <<servlet-replace-methodsecurity-with-globalmethodsecurity,revert the behavior>>.
== Reactive
=== Use `AuthorizationManager` for Method Security
If you run into trouble with this enhancement, you can instead <<reactive-change-to-useauthorizationmanager-false,revert the behavior>>.
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:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
2022-10-25 07:38:58 +08:00
----
====
changes to:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity
2022-10-25 07:38:58 +08:00
----
====
2022-10-27 02:52:37 +08:00
'''
2022-10-26 05:04:43 +08:00
2022-10-27 02:52:37 +08:00
[[revert]]
2022-10-26 05:04:43 +08:00
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.
2022-10-27 02:52:37 +08:00
== Revert Servlet
=== Don't Use `AuthorizationManager` in Method Security
2022-10-26 05:04:43 +08:00
To opt out of `AuthorizationManager` for Method Security, replace xref:servlet/authorization/method-security.adoc#jc-enable-method-security[method security] with xref:servlet/authorization/method-security.adoc#jc-enable-global-method-security[global method security]
2022-10-26 05:04:43 +08:00
2022-10-27 02:52:37 +08:00
For applications using xref:servlet/authorization/method-security.adoc#jc-enable-method-security[pre-post annotations], make sure to turn it on to reactivate the behavior.
2022-10-25 07:38:58 +08:00
2022-10-26 05:04:43 +08:00
For example, change:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableMethodSecurity
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableMethodSecurity
2022-10-25 07:38:58 +08:00
----
2022-10-27 02:52:37 +08:00
.Xml
[source,xml,role="secondary"]
----
<method-security/>
----
2022-10-25 07:38:58 +08:00
====
2022-10-26 05:04:43 +08:00
to:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableGlobalMethodSecurity(prePostEnabled = true)
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableGlobalMethodSecurity(prePostEnabled = true)
2022-10-25 07:38:58 +08:00
----
2022-10-27 02:52:37 +08:00
.Xml
[source,xml,role="secondary"]
----
<global-method-security pre-post-enabled="true"/>
----
2022-10-25 07:38:58 +08:00
====
2022-10-27 02:52:37 +08:00
Other usages can simply change {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableMethodSecurity.html[`@EnableMethodSecurity`] and xref:servlet/appendix/namespace/method-security.adoc#nsa-method-security[`<method-security>`] to {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableGlobalMethodSecurity.html[`@EnableGlobalMethodSecurity`] and xref:servlet/appendix/namespace/method-security.adoc#nsa-global-method-security[`<global-method-security>`], like so:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
2022-10-25 07:38:58 +08:00
----
2022-10-27 02:52:37 +08:00
.Xml
[source,xml,role="secondary"]
----
<method-security secured-enabled="true" pre-post-enabled="false"/>
----
2022-10-25 07:38:58 +08:00
====
2022-10-26 05:04:43 +08:00
should change to:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = false)
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = false)
2022-10-25 07:38:58 +08:00
----
2022-10-27 02:52:37 +08:00
.Xml
[source,xml,role="secondary"]
----
<global-method-security secured-enabled="true" pre-post-enabled="false"/>
----
2022-10-25 07:38:58 +08:00
====
2022-10-27 02:52:37 +08:00
== Revert Reactive
=== Don't Use `AuthorizationManager` in Method Security
2022-10-25 07:38:58 +08:00
2022-10-26 05:04:43 +08:00
To opt-out of {security-api-url}org/springframework/security/authorization/AuthorizationManager.html[`AuthorizationManager`] for reactive method security, add `useAuthorizationManager = false`:
2022-10-25 07:38:58 +08:00
====
.Java
[source,java,role="primary"]
----
@EnableReactiveMethodSecurity
----
.Kotlin
[source,kotlin,role="secondary"]
----
@EnableReactiveMethodSecurity
----
====
changes to:
====
.Java
[source,java,role="primary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity(useAuthorizationManager = false)
2022-10-25 07:38:58 +08:00
----
.Kotlin
[source,kotlin,role="secondary"]
----
2022-10-26 05:04:43 +08:00
@EnableReactiveMethodSecurity(useAuthorizationManager = false)
2022-10-25 07:38:58 +08:00
----
====