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

=== 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.