diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 5fb794c588..0b1059a751 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,7 +2,12 @@ * xref:prerequisites.adoc[Prerequisites] * xref:community.adoc[Community] * xref:whats-new.adoc[What's New] -* xref:migration.adoc[Migrating to 6.0] +* xref:migration/index.adoc[Migrating to 6.0] +** xref:migration/servlet/index.adoc[Servlet Migrations] +*** xref:migration/servlet/session-management.adoc[Session Management] +*** xref:migration/servlet/authentication.adoc[Authentication] +*** xref:migration/servlet/authorization.adoc[Authorization] +** xref:migration/reactive.adoc[Reactive Migrations] * 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 deleted file mode 100644 index fa6d815d7f..0000000000 --- a/docs/modules/ROOT/pages/migration.adoc +++ /dev/null @@ -1,438 +0,0 @@ -[[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 -ifdef::spring-security-version[] -xref:5.8.0@migration/index.adoc[its preparation steps] -endif::[] -ifndef::spring-security-version[] -its preparation steps -endif::[] -to simplify updating to 6.0 - -After updating to 5.8, follow this guide to perform any needed migration steps. - -Also, this guide includes ways to <> behaviors and its defaults, should you run into trouble. - -== Servlet - -In Spring Security 5, the default behavior is for the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontext[`SecurityContext`] to automatically be saved to the xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] using the xref:servlet/authentication/persistence.adoc#securitycontextpersistencefilter[`SecurityContextPersistenceFilter`]. -Saving must be done just prior to the `HttpServletResponse` being committed and just before `SecurityContextPersistenceFilter`. -Unfortunately, automatic persistence of the `SecurityContext` can surprise users when it is done prior to the request completing (i.e. just prior to committing the `HttpServletResponse`). -It also is complex to keep track of the state to determine if a save is necessary causing unnecessary writes to the `SecurityContextRepository` (i.e. `HttpSession`) at times. - -In Spring Security 6, the default behavior is that the xref:servlet/authentication/persistence.adoc#securitycontextholderfilter[`SecurityContextHolderFilter`] will only read the `SecurityContext` from `SecurityContextRepository` and populate it in the `SecurityContextHolder`. -Users now must explicitly save the `SecurityContext` with the `SecurityContextRepository` if they want the `SecurityContext` to persist between requests. -This removes ambiguity and improves performance by only requiring writing to the `SecurityContextRepository` (i.e. `HttpSession`) when it is necessary. - -If you are explicitly opting into Spring Security 6's new defaults, the following configuration can be removed to accept the Spring Security 6 defaults. - -include::partial$servlet/architecture/security-context-explicit.adoc[] - -=== Multiple SecurityContextRepository - -In Spring Security 5, the default xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] was `HttpSessionSecurityContextRepository`. - -In Spring Security 6, the default `SecurityContextRepository` is `DelegatingSecurityContextRepository`. -If you configured the `SecurityContextRepository` only for the purpose of updating to 6.0, you can remove it completely. - -=== Deprecation in SecurityContextRepository - -There are no further migration steps for this deprecation. - -[[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 - -There are no further migration steps for this feature. - -=== Use `AuthorizationManager` for Message Security - -In 6.0, `` defaults `use-authorization-manager` to `true`. -So, to complete migration, remove any `websocket-message-broker@use-authorization-manager=true` attribute. - -For example: - -==== -.Xml -[source,xml,role="primary"] ----- - ----- -==== - -changes to: - -==== -.Xml -[source,xml,role="primary"] ----- - ----- -==== - -There are no further migrations steps for Java or Kotlin for this feature. - -=== Use `AuthorizationManager` for Request Security - -In 6.0, `` defaults `once-per-request` to `false`, `filter-all-dispatcher-types` to `true`, and `use-authorization-manager` to `true`. -Also, xref:servlet/authorization/authorize-requests.adoc#filtersecurityinterceptor-every-request[`authorizeRequests#filterSecurityInterceptorOncePerRequest`] defaults to `false` and xref:servlet/authorization/authorize-http-requests.adoc[`authorizeHttpRequests#filterAllDispatcherTypes`] defaults to `true`. -So, to complete migration, any defaults values can be removed. - -For example, if you opted in to the 6.0 default for `filter-all-dispatcher-types` or `authorizeHttpRequests#filterAllDispatcherTypes` like so: - -==== -.Java -[source,java,role="primary"] ----- -http - .authorizeHttpRequests((authorize) -> authorize - .filterAllDispatcherTypes(true) - // ... - ) ----- - -.Kotlin -[source,java,role="secondary"] ----- -http { - authorizeHttpRequests { - filterAllDispatcherTypes = true - // ... - } -} ----- - -.Xml -[source,xml,role="secondary"] ----- - ----- -==== - -then the defaults may be removed: - -==== -.Java -[source,java,role="primary"] ----- -http - .authorizeHttpRequests((authorize) -> authorize - // ... - ) ----- - -.Kotlin -[source,java,role="secondary"] ----- -http { - authorizeHttpRequests { - // ... - } -} ----- - -.Xml -[source,xml,role="secondary"] ----- - ----- -==== - -[NOTE] -==== -`once-per-request` applies only when `use-authorization-manager="false"` and `filter-all-dispatcher-types` only applies when `use-authorization-manager="true"` -==== - -=== Propagate ``AuthenticationServiceException``s - -{security-api-url}org/springframework/security/web/authentication/AuthenticationFilter.html[`AuthenticationFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/authentication/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`]. -Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. - -So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: - -==== -.Java -[source,java,role="primary"] ----- -AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); -AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); -handler.setRethrowAuthenticationServiceException(true); -authenticationFilter.setAuthenticationFailureHandler(handler); ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) -val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) -handler.setRethrowAuthenticationServiceException(true) -authenticationFilter.setAuthenticationFailureHandler(handler) ----- - -.Xml -[source,xml,role="secondary"] ----- - - - - - - - - ----- -==== - -changes to: - -==== -.Java -[source,java,role="primary"] ----- -AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); -AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); -authenticationFilter.setAuthenticationFailureHandler(handler); ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) -val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) -authenticationFilter.setAuthenticationFailureHandler(handler) ----- - -.Xml -[source,xml,role="secondary"] ----- - - - - - - - - ----- -==== - -[[servlet-opt-in-sha256-rememberme]] -=== Use SHA-256 in Remember Me - -In 6.0, the `TokenBasedRememberMeServices` uses SHA-256 to encode and match the token. -To complete the migration, any default values can be removed. - -For example, if you opted in to the 6.0 default for `encodingAlgorithm` and `matchingAlgorithm` like so: - -==== -.Java -[source,java,role="primary"] ----- -@Configuration -@EnableWebSecurity -public class SecurityConfig { - @Bean - SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { - http - // ... - .rememberMe((remember) -> remember - .rememberMeServices(rememberMeServices) - ); - return http.build(); - } - @Bean - RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { - RememberMeTokenAlgorithm encodingAlgorithm = RememberMeTokenAlgorithm.SHA256; - TokenBasedRememberMeServices rememberMe = new TokenBasedRememberMeServices(myKey, userDetailsService, encodingAlgorithm); - rememberMe.setMatchingAlgorithm(RememberMeTokenAlgorithm.SHA256); - return rememberMe; - } -} ----- -.XML -[source,xml,role="secondary"] ----- - - - - - - - - - ----- -==== - -then the defaults can be removed: - -==== -.Java -[source,java,role="primary"] ----- -@Configuration -@EnableWebSecurity -public class SecurityConfig { - @Bean - SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { - http - // ... - .rememberMe((remember) -> remember - .rememberMeServices(rememberMeServices) - ); - return http.build(); - } - @Bean - RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { - return new TokenBasedRememberMeServices(myKey, userDetailsService); - } -} ----- -.XML -[source,xml,role="secondary"] ----- - - - - - - - ----- -==== - -[[use-new-requestmatchers]] -=== Use the new `requestMatchers` methods - -There are no further migration steps for this feature. - -[[use-new-security-matchers]] -=== Use the new `securityMatchers` methods - -There are no further migration steps for this feature. - -=== Remove CAS support - -In Spring Security 6.0, the CAS support https://github.com/spring-projects/spring-security/issues/10441[has been removed]. -There is no direct replacement for it, however, it is possible to https://apereo.github.io/cas/6.6.x/authentication/OAuth-Authentication.html[configure your CAS server to act as an OAuth 2.0 Authentication Provider] and use the xref::servlet/oauth2/index.adoc[OAuth 2.0 support in Spring Security]. - -=== Default authorities for oauth2Login() - -In Spring Security 5, the default `GrantedAuthority` given to a user that authenticates with an OAuth2 or OpenID Connect 1.0 provider (via `oauth2Login()`) is `ROLE_USER`. - -In Spring Security 6, the default authority given to a user authenticating with an OAuth2 provider is `OAUTH2_USER`. -The default authority given to a user authenticating with an OpenID Connect 1.0 provider is `OIDC_USER`. -If you configured the `GrantedAuthoritiesMapper` only for the purpose of updating to 6.0, you can remove it completely. - -== Reactive - -=== Use `AuthorizationManager` for Method Security - -In 6.0, `@EnableReactiveMethodSecurity` defaults `useAuthorizationManager` to `true`. -So, to complete migration, {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableReactiveMethodSecurity.html[`@EnableReactiveMethodSecurity`] remove the `useAuthorizationManager` attribute: - -==== -.Java -[source,java,role="primary"] ----- -@EnableReactiveMethodSecurity(useAuthorizationManager = true) ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -@EnableReactiveMethodSecurity(useAuthorizationManager = true) ----- -==== - -changes to: - -==== -.Java -[source,java,role="primary"] ----- -@EnableReactiveMethodSecurity ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -@EnableReactiveMethodSecurity ----- -==== - -''' - -=== Propagate ``AuthenticationServiceException``s - -{security-api-url}org/springframework/security/web/server/authentication/AuthenticationWebFilter.html[`AuthenticationWebFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/web/server/ServerAuthenticationEntryPoint.html[`ServerAuthenticationEntryPoint`]. -Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. - -So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: - -==== -.Java -[source,java,role="primary"] ----- -AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); -bearerFailureHandler.setRethrowAuthenticationServiceException(true); -AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); -basicFailureHandler.setRethrowAuthenticationServiceException(true); ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) -bearerFailureHandler.setRethrowAuthenticationServiceException(true) -val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) -basicFailureHandler.setRethrowAuthenticationServiceException(true) ----- -==== - -changes to: - -==== -.Java -[source,java,role="primary"] ----- -AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); -AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); ----- - -.Kotlin -[source,kotlin,role="secondary"] ----- -val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) -val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) ----- -==== - -[NOTE] -==== -If you configured the `ServerAuthenticationFailureHandler` only for the purpose of updating to 6.0, you can remove it completely. -==== - -[[revert]] -If you are running into trouble with any of the 6.0 changes, please first try to apply the following changes to get you up and running. -It's more important to stay on 6.0 and get the security improvements. - -== Revert Servlet - -== Revert Reactive diff --git a/docs/modules/ROOT/pages/migration/index.adoc b/docs/modules/ROOT/pages/migration/index.adoc new file mode 100644 index 0000000000..56b66e42e5 --- /dev/null +++ b/docs/modules/ROOT/pages/migration/index.adoc @@ -0,0 +1,30 @@ +[[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 +ifdef::spring-security-version[] +xref:5.8.0@migration/index.adoc[its preparation steps] +endif::[] +ifndef::spring-security-version[] +its preparation steps +endif::[] +to simplify updating to 6.0 + +After updating to 5.8, follow this guide to perform any remaining migration or cleanup steps. + +And recall that if you run into trouble, the preparation guide includes opt-out steps to revert to 5.x behaviors. + +== Update to Spring Security 6.0 + +The first step is to ensure you are the latest patch release of Spring Boot 3.0. +Next, you should ensure you are on the latest patch release of Spring Security 6.0. +For directions, on how to update to Spring Security 6.0 visit the xref:getting-spring-security.adoc[] section of the reference guide. + +== Update Package Names + +Now that you are updated, you need to change your `javax` imports to `jakarta` imports. + +== Perform Application-Specific Steps + +Next, there are steps you need to perform based on whether it is a xref:migration/servlet/index.adoc[Servlet] or xref:migration/reactive.adoc[Reactive] application. diff --git a/docs/modules/ROOT/pages/migration/reactive.adoc b/docs/modules/ROOT/pages/migration/reactive.adoc new file mode 100644 index 0000000000..c67e8411fb --- /dev/null +++ b/docs/modules/ROOT/pages/migration/reactive.adoc @@ -0,0 +1,88 @@ += Reactive + +If you have already performed the xref:migration/index.adoc[initial migration steps] for your Reactive application, you're now ready to perform steps specific to Reactive applications. + +== Use `AuthorizationManager` for Method Security + +In 6.0, `@EnableReactiveMethodSecurity` defaults `useAuthorizationManager` to `true`. +So, to complete migration, {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableReactiveMethodSecurity.html[`@EnableReactiveMethodSecurity`] remove the `useAuthorizationManager` attribute: + +==== +.Java +[source,java,role="primary"] +---- +@EnableReactiveMethodSecurity(useAuthorizationManager = true) +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableReactiveMethodSecurity(useAuthorizationManager = true) +---- +==== + +changes to: + +==== +.Java +[source,java,role="primary"] +---- +@EnableReactiveMethodSecurity +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +@EnableReactiveMethodSecurity +---- +==== + +== Propagate ``AuthenticationServiceException``s + +{security-api-url}org/springframework/security/web/server/authentication/AuthenticationWebFilter.html[`AuthenticationWebFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/web/server/ServerAuthenticationEntryPoint.html[`ServerAuthenticationEntryPoint`]. +Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. + +So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: + +==== +.Java +[source,java,role="primary"] +---- +AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); +bearerFailureHandler.setRethrowAuthenticationServiceException(true); +AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); +basicFailureHandler.setRethrowAuthenticationServiceException(true); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) +bearerFailureHandler.setRethrowAuthenticationServiceException(true) +val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) +basicFailureHandler.setRethrowAuthenticationServiceException(true) +---- +==== + +changes to: + +==== +.Java +[source,java,role="primary"] +---- +AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint); +AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint) +val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint) +---- +==== + +[NOTE] +==== +If you configured the `ServerAuthenticationFailureHandler` only for the purpose of updating to 6.0, you can remove it completely. +==== diff --git a/docs/modules/ROOT/pages/migration/servlet/authentication.adoc b/docs/modules/ROOT/pages/migration/servlet/authentication.adoc new file mode 100644 index 0000000000..38d4ae7a14 --- /dev/null +++ b/docs/modules/ROOT/pages/migration/servlet/authentication.adoc @@ -0,0 +1,171 @@ += Authentication Migrations + +The following steps relate to how to finish migrating authentication support. + +== Propagate ``AuthenticationServiceException``s + +{security-api-url}org/springframework/security/web/authentication/AuthenticationFilter.html[`AuthenticationFilter`] propagates {security-api-url}org/springframework/security/authentication/AuthenticationServiceException.html[``AuthenticationServiceException``]s to the {security-api-url}org/springframework/security/authentication/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`]. +Because ``AuthenticationServiceException``s represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container. + +So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so: + +==== +.Java +[source,java,role="primary"] +---- +AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); +AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); +handler.setRethrowAuthenticationServiceException(true); +authenticationFilter.setAuthenticationFailureHandler(handler); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) +val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) +handler.setRethrowAuthenticationServiceException(true) +authenticationFilter.setAuthenticationFailureHandler(handler) +---- + +.Xml +[source,xml,role="secondary"] +---- + + + + + + + + +---- +==== + +changes to: + +==== +.Java +[source,java,role="primary"] +---- +AuthenticationFilter authenticationFilter = new AuthenticationFilter(...); +AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...); +authenticationFilter.setAuthenticationFailureHandler(handler); +---- + +.Kotlin +[source,kotlin,role="secondary"] +---- +val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...) +val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...) +authenticationFilter.setAuthenticationFailureHandler(handler) +---- + +.Xml +[source,xml,role="secondary"] +---- + + + + + + + + +---- +==== + +[[servlet-opt-in-sha256-rememberme]] +== Use SHA-256 in Remember Me + +In 6.0, the `TokenBasedRememberMeServices` uses SHA-256 to encode and match the token. +To complete the migration, any default values can be removed. + +For example, if you opted in to the 6.0 default for `encodingAlgorithm` and `matchingAlgorithm` like so: + +==== +.Java +[source,java,role="primary"] +---- +@Configuration +@EnableWebSecurity +public class SecurityConfig { + @Bean + SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { + http + // ... + .rememberMe((remember) -> remember + .rememberMeServices(rememberMeServices) + ); + return http.build(); + } + @Bean + RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { + RememberMeTokenAlgorithm encodingAlgorithm = RememberMeTokenAlgorithm.SHA256; + TokenBasedRememberMeServices rememberMe = new TokenBasedRememberMeServices(myKey, userDetailsService, encodingAlgorithm); + rememberMe.setMatchingAlgorithm(RememberMeTokenAlgorithm.SHA256); + return rememberMe; + } +} +---- +.XML +[source,xml,role="secondary"] +---- + + + + + + + + + +---- +==== + +then the defaults can be removed: + +==== +.Java +[source,java,role="primary"] +---- +@Configuration +@EnableWebSecurity +public class SecurityConfig { + @Bean + SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception { + http + // ... + .rememberMe((remember) -> remember + .rememberMeServices(rememberMeServices) + ); + return http.build(); + } + @Bean + RememberMeServices rememberMeServices(UserDetailsService userDetailsService) { + return new TokenBasedRememberMeServices(myKey, userDetailsService); + } +} +---- +.XML +[source,xml,role="secondary"] +---- + + + + + + + +---- +==== + +== Default authorities for oauth2Login() + +In Spring Security 5, the default `GrantedAuthority` given to a user that authenticates with an OAuth2 or OpenID Connect 1.0 provider (via `oauth2Login()`) is `ROLE_USER`. + +In Spring Security 6, the default authority given to a user authenticating with an OAuth2 provider is `OAUTH2_USER`. +The default authority given to a user authenticating with an OpenID Connect 1.0 provider is `OIDC_USER`. +If you configured the `GrantedAuthoritiesMapper` only for the purpose of updating to 6.0, you can remove it completely. diff --git a/docs/modules/ROOT/pages/migration/servlet/authorization.adoc b/docs/modules/ROOT/pages/migration/servlet/authorization.adoc new file mode 100644 index 0000000000..c77f2bd589 --- /dev/null +++ b/docs/modules/ROOT/pages/migration/servlet/authorization.adoc @@ -0,0 +1,105 @@ += Authorization Migrations + +The following steps relate to how to finish migrating authorization support. + +== Use `AuthorizationManager` for Method Security + +There are no further migration steps for this feature. + +== Use `AuthorizationManager` for Message Security + +In 6.0, `` defaults `use-authorization-manager` to `true`. +So, to complete migration, remove any `websocket-message-broker@use-authorization-manager=true` attribute. + +For example: + +==== +.Xml +[source,xml,role="primary"] +---- + +---- +==== + +changes to: + +==== +.Xml +[source,xml,role="primary"] +---- + +---- +==== + +There are no further migrations steps for Java or Kotlin for this feature. + +== Use `AuthorizationManager` for Request Security + +In 6.0, `` defaults `once-per-request` to `false`, `filter-all-dispatcher-types` to `true`, and `use-authorization-manager` to `true`. +Also, xref:servlet/authorization/authorize-requests.adoc#filtersecurityinterceptor-every-request[`authorizeRequests#filterSecurityInterceptorOncePerRequest`] defaults to `false` and xref:servlet/authorization/authorize-http-requests.adoc[`authorizeHttpRequests#filterAllDispatcherTypes`] defaults to `true`. +So, to complete migration, any defaults values can be removed. + +For example, if you opted in to the 6.0 default for `filter-all-dispatcher-types` or `authorizeHttpRequests#filterAllDispatcherTypes` like so: + +==== +.Java +[source,java,role="primary"] +---- +http + .authorizeHttpRequests((authorize) -> authorize + .filterAllDispatcherTypes(true) + // ... + ) +---- + +.Kotlin +[source,java,role="secondary"] +---- +http { + authorizeHttpRequests { + filterAllDispatcherTypes = true + // ... + } +} +---- + +.Xml +[source,xml,role="secondary"] +---- + +---- +==== + +then the defaults may be removed: + +==== +.Java +[source,java,role="primary"] +---- +http + .authorizeHttpRequests((authorize) -> authorize + // ... + ) +---- + +.Kotlin +[source,java,role="secondary"] +---- +http { + authorizeHttpRequests { + // ... + } +} +---- + +.Xml +[source,xml,role="secondary"] +---- + +---- +==== + +[NOTE] +==== +`once-per-request` applies only when `use-authorization-manager="false"` and `filter-all-dispatcher-types` only applies when `use-authorization-manager="true"` +==== diff --git a/docs/modules/ROOT/pages/migration/servlet/index.adoc b/docs/modules/ROOT/pages/migration/servlet/index.adoc new file mode 100644 index 0000000000..adc75685a6 --- /dev/null +++ b/docs/modules/ROOT/pages/migration/servlet/index.adoc @@ -0,0 +1,4 @@ += Servlet Migrations +:page-section-summary-toc: 1 + +If you have already performed the xref:migration/index.adoc[initial migration steps] for your Servlet application, you're now ready to perform steps specific to Servlet applications. diff --git a/docs/modules/ROOT/pages/migration/servlet/session-management.adoc b/docs/modules/ROOT/pages/migration/servlet/session-management.adoc new file mode 100644 index 0000000000..0b1533ab3c --- /dev/null +++ b/docs/modules/ROOT/pages/migration/servlet/session-management.adoc @@ -0,0 +1,43 @@ += Session Management Migrations + +The following steps relate to how to finish migrating session management support. + +== Require Explicit Saving of SecurityContextRepository + +In Spring Security 5, the default behavior is for the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontext[`SecurityContext`] to automatically be saved to the xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] using the xref:servlet/authentication/persistence.adoc#securitycontextpersistencefilter[`SecurityContextPersistenceFilter`]. +Saving must be done just prior to the `HttpServletResponse` being committed and just before `SecurityContextPersistenceFilter`. +Unfortunately, automatic persistence of the `SecurityContext` can surprise users when it is done prior to the request completing (i.e. just prior to committing the `HttpServletResponse`). +It also is complex to keep track of the state to determine if a save is necessary causing unnecessary writes to the `SecurityContextRepository` (i.e. `HttpSession`) at times. + +In Spring Security 6, the default behavior is that the xref:servlet/authentication/persistence.adoc#securitycontextholderfilter[`SecurityContextHolderFilter`] will only read the `SecurityContext` from `SecurityContextRepository` and populate it in the `SecurityContextHolder`. +Users now must explicitly save the `SecurityContext` with the `SecurityContextRepository` if they want the `SecurityContext` to persist between requests. +This removes ambiguity and improves performance by only requiring writing to the `SecurityContextRepository` (i.e. `HttpSession`) when it is necessary. + +If you are explicitly opting into Spring Security 6's new defaults, the following configuration can be removed to accept the Spring Security 6 defaults. + +include::partial$servlet/architecture/security-context-explicit.adoc[] + +== Multiple SecurityContextRepository + +In Spring Security 5, the default xref:servlet/authentication/persistence.adoc#securitycontextrepository[`SecurityContextRepository`] was `HttpSessionSecurityContextRepository`. + +In Spring Security 6, the default `SecurityContextRepository` is `DelegatingSecurityContextRepository`. +If you configured the `SecurityContextRepository` only for the purpose of updating to 6.0, you can remove it completely. + +== Deprecation in SecurityContextRepository + +There are no further migration steps for this deprecation. + +[[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[]