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

[[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 the steps below to minimize changes when updating to 6.0.

== Servlet

[[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

xref:servlet/authorization/method-security.adoc[Method Security] has been xref:servlet/authorization/method-security.adoc#jc-enable-method-security[simplified] through {security-api-url}org/springframework/security/authorization/AuthorizationManager.html[the `AuthorizationManager` API] and direct use of Spring AOP.

'''

[[servlet-replace-globalmethodsecurity-with-methodsecurity]]
[%interactive]
* [ ] Replace xref:servlet/authorization/method-security.adoc#jc-enable-global-method-security[global method security] with xref:servlet/authorization/method-security.adoc#jc-enable-method-security[method security]

{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>`] are deprecated in favor of {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>`], respectively.
The new annotation and XML element activate Spring's xref:servlet/authorization/method-security.adoc#jc-enable-method-security[pre-post annotations] by default and use `AuthorizationManager` internally.

This means that the following two listings are functionally equivalent:

====
.Java
[source,java,role="primary"]
----
@EnableGlobalMethodSecurity(prePostEnabled = true)
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableGlobalMethodSecurity(prePostEnabled = true)
----

.Xml
[source,xml,role="secondary"]
----
<global-method-security pre-post-enabled="true"/>
----
====

and:

====
.Java
[source,java,role="primary"]
----
@EnableMethodSecurity
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableMethodSecurity
----

.Xml
[source,xml,role="secondary"]
----
<method-security/>
----
====

For applications not using the pre-post annotations, make sure to turn it off to avoid activating unwanted behavior.

For example, a listing like:

====
.Java
[source,java,role="primary"]
----
@EnableGlobalMethodSecurity(securedEnabled = true)
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableGlobalMethodSecurity(securedEnabled = true)
----

.Xml
[source,xml,role="secondary"]
----
<global-method-security secured-enabled="true"/>
----
====

should change to:

====
.Java
[source,java,role="primary"]
----
@EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
----

.Xml
[source,xml,role="secondary"]
----
<method-security secured-enabled="true" pre-post-enabled="false"/>
----
====

'''

[[servlet-replace-permissionevaluator-bean-with-methodsecurityexpression-handler]]
[%interactive]
* [ ] Publish a `MethodSecurityExpressionHandler` instead of a `PermissionEvaluator`

`@EnableMethodSecurity` does not pick up a `PermissionEvaluator`.
This helps keep its API simple.

If you have a custom {security-api-url}org/springframework/security/access/PermissionEvaluator.html[`PermissionEvaluator`] `@Bean`, please change it from:

====
.Java
[source,java,role="primary"]
----
@Bean
static PermissionEvaluator permissionEvaluator() {
	// ... your evaluator
}
----

.Kotlin
[source,kotlin,role="secondary"]
----
companion object {
    @Bean
    fun permissionEvaluator(): PermissionEvaluator {
        // ... your evaluator
    }
}
----
====

to:

====
.Java
[source,java,role="primary"]
----
@Bean
static MethodSecurityExpressionHandler expressionHandler() {
    var expressionHandler = new DefaultMethodSecurityExpressionHandler();
    expressionHandler.setPermissionEvaluator(myPermissionEvaluator);
    return expressionHandler;
}
----

.Kotlin
[source,kotlin,role="secondary"]
----
companion object {
    @Bean
    fun expressionHandler(): MethodSecurityExpressionHandler {
        val expressionHandler = DefaultMethodSecurityExpressionHandler
        expressionHandler.setPermissionEvaluator(myPermissionEvaluator)
        return expressionHandler
    }
}
----
====

'''

[[servlet-check-for-annotationconfigurationexceptions]]
[%interactive]
* [ ] Check for ``AnnotationConfigurationException``s

`@EnableMethodSecurity` and `<method-security>` activate stricter enforcement of Spring Security's non-repeatable or otherwise incompatible annotations.
If after moving to either you see ``AnnotationConfigurationException``s in your logs, follow the instructions in the exception message to clean up your application's method security annotation usage.

== Reactive

=== Use `AuthorizationManager` for Method Security

xref:reactive/authorization/method.adoc[Method Security] has been xref:reactive/authorization/method.adoc#jc-enable-reactive-method-security-authorization-manager[improved] through {security-api-url}org/springframework/security/authorization/AuthorizationManager.html[the `AuthorizationManager` API] and direct use of Spring AOP.

'''

[[reactive-change-to-useauthorizationmanager]]
[%interactive]
* [ ] Change `useAuthorizationManager` to `true`

In Spring Security 5.8, `useAuthorizationManager` was added to {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableReactiveMethodSecurity.html[`@EnableReactiveMethodSecurity`] to allow applications to opt-in to ``AuthorizationManager``'s features.

To opt in, change `useAuthorizationManager` to `true` like so:

====
.Java
[source,java,role="primary"]
----
@EnableReactiveMethodSecurity
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableReactiveMethodSecurity
----
====

changes to:

====
.Java
[source,java,role="primary"]
----
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
----

.Kotlin
[source,kotlin,role="secondary"]
----
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
----
====

[NOTE]
=====
In 6.0, `useAuthorizationManager` defaults to `true`.
=====

'''

[[reactive-check-for-annotationconfigurationexceptions]]
[%interactive]
* [ ] Check for ``AnnotationConfigurationException``s

`useAuthorizationManager` activates stricter enforcement of Spring Security's non-repeatable or otherwise incompatible annotations.
If after turning on `useAuthorizationManager` you see ``AnnotationConfigurationException``s in your logs, follow the instructions in the exception message to clean up your application's method security annotation usage.