migration.adoc 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261
  1. [[migration]]
  2. = Migrating to 6.0
  3. The Spring Security team has prepared the 5.8 release to simplify upgrading to Spring Security 6.0.
  4. Use 5.8 and the steps below to minimize changes when
  5. ifdef::spring-security-version[]
  6. xref:6.0.0@migration.adoc[updating to 6.0]
  7. endif::[]
  8. ifndef::spring-security-version[]
  9. updating to 6.0
  10. endif::[]
  11. .
  12. == Servlet
  13. [[requestcache-query-optimization]]
  14. === Optimize Querying of `RequestCache`
  15. In Spring Security 5, the default behavior is to query the xref:servlet/architecture.adoc#savedrequests[saved request] on every request.
  16. 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.
  17. In Spring Security 6, the default is that `RequestCache` will only be queried for a cached request if the HTTP parameter `continue` is defined.
  18. This allows Spring Security to avoid unnecessarily reading the `HttpSession` with the `RequestCache`.
  19. In Spring Security 5 the default is to use `HttpSessionRequestCache` which will be queried for a cached request on every request.
  20. 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:
  21. include::partial$servlet/architecture/request-cache-continue.adoc[]
  22. === Use `AuthorizationManager` for Method Security
  23. 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.
  24. '''
  25. [[servlet-replace-globalmethodsecurity-with-methodsecurity]]
  26. [%interactive]
  27. * [ ] 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]
  28. {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.
  29. 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.
  30. This means that the following two listings are functionally equivalent:
  31. ====
  32. .Java
  33. [source,java,role="primary"]
  34. ----
  35. @EnableGlobalMethodSecurity(prePostEnabled = true)
  36. ----
  37. .Kotlin
  38. [source,kotlin,role="secondary"]
  39. ----
  40. @EnableGlobalMethodSecurity(prePostEnabled = true)
  41. ----
  42. .Xml
  43. [source,xml,role="secondary"]
  44. ----
  45. <global-method-security pre-post-enabled="true"/>
  46. ----
  47. ====
  48. and:
  49. ====
  50. .Java
  51. [source,java,role="primary"]
  52. ----
  53. @EnableMethodSecurity
  54. ----
  55. .Kotlin
  56. [source,kotlin,role="secondary"]
  57. ----
  58. @EnableMethodSecurity
  59. ----
  60. .Xml
  61. [source,xml,role="secondary"]
  62. ----
  63. <method-security/>
  64. ----
  65. ====
  66. For applications not using the pre-post annotations, make sure to turn it off to avoid activating unwanted behavior.
  67. For example, a listing like:
  68. ====
  69. .Java
  70. [source,java,role="primary"]
  71. ----
  72. @EnableGlobalMethodSecurity(securedEnabled = true)
  73. ----
  74. .Kotlin
  75. [source,kotlin,role="secondary"]
  76. ----
  77. @EnableGlobalMethodSecurity(securedEnabled = true)
  78. ----
  79. .Xml
  80. [source,xml,role="secondary"]
  81. ----
  82. <global-method-security secured-enabled="true"/>
  83. ----
  84. ====
  85. should change to:
  86. ====
  87. .Java
  88. [source,java,role="primary"]
  89. ----
  90. @EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
  91. ----
  92. .Kotlin
  93. [source,kotlin,role="secondary"]
  94. ----
  95. @EnableMethodSecurity(securedEnabled = true, prePostEnabled = false)
  96. ----
  97. .Xml
  98. [source,xml,role="secondary"]
  99. ----
  100. <method-security secured-enabled="true" pre-post-enabled="false"/>
  101. ----
  102. ====
  103. '''
  104. [[servlet-replace-permissionevaluator-bean-with-methodsecurityexpression-handler]]
  105. [%interactive]
  106. * [ ] Publish a `MethodSecurityExpressionHandler` instead of a `PermissionEvaluator`
  107. `@EnableMethodSecurity` does not pick up a `PermissionEvaluator`.
  108. This helps keep its API simple.
  109. If you have a custom {security-api-url}org/springframework/security/access/PermissionEvaluator.html[`PermissionEvaluator`] `@Bean`, please change it from:
  110. ====
  111. .Java
  112. [source,java,role="primary"]
  113. ----
  114. @Bean
  115. static PermissionEvaluator permissionEvaluator() {
  116. // ... your evaluator
  117. }
  118. ----
  119. .Kotlin
  120. [source,kotlin,role="secondary"]
  121. ----
  122. companion object {
  123. @Bean
  124. fun permissionEvaluator(): PermissionEvaluator {
  125. // ... your evaluator
  126. }
  127. }
  128. ----
  129. ====
  130. to:
  131. ====
  132. .Java
  133. [source,java,role="primary"]
  134. ----
  135. @Bean
  136. static MethodSecurityExpressionHandler expressionHandler() {
  137. var expressionHandler = new DefaultMethodSecurityExpressionHandler();
  138. expressionHandler.setPermissionEvaluator(myPermissionEvaluator);
  139. return expressionHandler;
  140. }
  141. ----
  142. .Kotlin
  143. [source,kotlin,role="secondary"]
  144. ----
  145. companion object {
  146. @Bean
  147. fun expressionHandler(): MethodSecurityExpressionHandler {
  148. val expressionHandler = DefaultMethodSecurityExpressionHandler
  149. expressionHandler.setPermissionEvaluator(myPermissionEvaluator)
  150. return expressionHandler
  151. }
  152. }
  153. ----
  154. ====
  155. '''
  156. [[servlet-check-for-annotationconfigurationexceptions]]
  157. [%interactive]
  158. * [ ] Check for ``AnnotationConfigurationException``s
  159. `@EnableMethodSecurity` and `<method-security>` activate stricter enforcement of Spring Security's non-repeatable or otherwise incompatible annotations.
  160. 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.
  161. == Reactive
  162. === Use `AuthorizationManager` for Method Security
  163. 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.
  164. '''
  165. [[reactive-change-to-useauthorizationmanager]]
  166. [%interactive]
  167. * [ ] Change `useAuthorizationManager` to `true`
  168. 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.
  169. To opt in, change `useAuthorizationManager` to `true` like so:
  170. ====
  171. .Java
  172. [source,java,role="primary"]
  173. ----
  174. @EnableReactiveMethodSecurity
  175. ----
  176. .Kotlin
  177. [source,kotlin,role="secondary"]
  178. ----
  179. @EnableReactiveMethodSecurity
  180. ----
  181. ====
  182. changes to:
  183. ====
  184. .Java
  185. [source,java,role="primary"]
  186. ----
  187. @EnableReactiveMethodSecurity(useAuthorizationManager = true)
  188. ----
  189. .Kotlin
  190. [source,kotlin,role="secondary"]
  191. ----
  192. @EnableReactiveMethodSecurity(useAuthorizationManager = true)
  193. ----
  194. ====
  195. [NOTE]
  196. =====
  197. In 6.0, `useAuthorizationManager` defaults to `true`.
  198. =====
  199. '''
  200. [[reactive-check-for-annotationconfigurationexceptions]]
  201. [%interactive]
  202. * [ ] Check for ``AnnotationConfigurationException``s
  203. `useAuthorizationManager` activates stricter enforcement of Spring Security's non-repeatable or otherwise incompatible annotations.
  204. 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.