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

=== Change `@EnableGlobalMethodSecurity` to `@EnableMethodSecurity`

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.

The public API difference between these two annotations is that {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableMethodSecurity.html[`@EnableMethodSecurity`] defaults `prePostEnabled` to `true`, while {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableGlobalMethodSecurity.html[`@EnableGlobalMethodSecurity`] defaults it to `false`.
Also, `@EnableMethodSecurity` internally uses `AuthorizationManager` while `@EnableGlobalMethodSecurity` does not.

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

changes to:

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

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

For applications not using `prePostEnabled`, 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)
----
====

should change to:

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

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

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

==== Publish your custom `PermissionEvaluator` as a `MethodSecurityExpressionHandler`

`@EnableMethodSecurity` does not pick up a `PermissionEvaluator` bean.
Instead, it picks up the more generic `MethodSecurityExpressionHandler` to simplify the API.

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
PermissionEvaluator permissionEvaluator() {
	// ... your evaluator
}
----

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

to:

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

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

== Reactive

=== Activate `AuthorizationManager` in `@EnableReactiveMethodSecurity`

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.

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 that in 6.0, `useAuthorizationManager` defaults to `true`.

Additionally, note that `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.