From e505bc3af40ee9d557afb7efacd476da256814d1 Mon Sep 17 00:00:00 2001 From: Josh Cummings Date: Mon, 24 Oct 2022 17:38:58 -0600 Subject: [PATCH 1/2] Add Method Security Preparation Steps --- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/migration.adoc | 183 +++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 docs/modules/ROOT/pages/migration.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index a4b0fb6cf4..a8a7057835 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,6 +2,7 @@ * xref:prerequisites.adoc[Prerequisites] * xref:community.adoc[Community] * xref:whats-new.adoc[What's New] +* xref:migration.adoc[Migrating for 6.0] * xref:getting-spring-security.adoc[Getting Spring Security] * xref:features/index.adoc[Features] ** xref:features/authentication/index.adoc[Authentication] diff --git a/docs/modules/ROOT/pages/migration.adoc b/docs/modules/ROOT/pages/migration.adoc new file mode 100644 index 0000000000..f1ace7c717 --- /dev/null +++ b/docs/modules/ROOT/pages/migration.adoc @@ -0,0 +1,183 @@ +[[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. + + From 04fa5af7946dd3b9b3821ea7a68e964122d09396 Mon Sep 17 00:00:00 2001 From: Josh Cummings Date: Mon, 24 Oct 2022 17:39:45 -0600 Subject: [PATCH 2/2] Add Missing Doc Header The EnableMethodSecurity section --- .../ROOT/pages/servlet/authorization/method-security.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc index 94b321fd7e..13a7a3c2ef 100644 --- a/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc +++ b/docs/modules/ROOT/pages/servlet/authorization/method-security.adoc @@ -6,6 +6,7 @@ It provides support for JSR-250 annotation security as well as the framework's o From 3.0 you can also make use of new xref:servlet/authorization/expression-based.adoc#el-access[expression-based annotations]. You can apply security to a single bean, using the `intercept-methods` element to decorate the bean declaration, or you can secure multiple beans across the entire service layer using the AspectJ style pointcuts. +[[jc-enable-method-security]] == EnableMethodSecurity In Spring Security 5.6, we can enable annotation-based security using the `@EnableMethodSecurity` annotation on any `@Configuration` instance.