Josh Cummings
parent
34102a6531
commit
3f5d8b39ce
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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 <<revert,revert to 5.x>> 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, `<websocket-message-broker>` 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"]
|
||||
----
|
||||
<websocket-message-broker use-authorization-manager="true"/>
|
||||
----
|
||||
====
|
||||
|
||||
changes to:
|
||||
|
||||
====
|
||||
.Xml
|
||||
[source,xml,role="primary"]
|
||||
----
|
||||
<websocket-message-broker/>
|
||||
----
|
||||
====
|
||||
|
||||
There are no further migrations steps for Java or Kotlin for this feature.
|
||||
|
||||
=== Use `AuthorizationManager` for Request Security
|
||||
|
||||
In 6.0, `<http>` 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"]
|
||||
----
|
||||
<http use-authorization-manager="true" filter-all-dispatcher-types="true"/>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<http/>
|
||||
----
|
||||
====
|
||||
|
||||
[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"]
|
||||
----
|
||||
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
|
||||
<!-- ... -->
|
||||
<property ref="authenticationFailureHandler"/>
|
||||
</bean>
|
||||
|
||||
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
|
||||
<property name="rethrowAuthenticationServiceException" value="true"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
|
||||
<!-- ... -->
|
||||
<property ref="authenticationFailureHandler"/>
|
||||
</bean>
|
||||
|
||||
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
|
||||
<!-- ... -->
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
[[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"]
|
||||
----
|
||||
<http>
|
||||
<remember-me services-ref="rememberMeServices"/>
|
||||
</http>
|
||||
<bean id="rememberMeServices" class=
|
||||
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
|
||||
<property name="userDetailsService" ref="myUserDetailsService"/>
|
||||
<property name="key" value="springRocks"/>
|
||||
<property name="matchingAlgorithm" value="SHA256"/>
|
||||
<property name="encodingAlgorithm" value="SHA256"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<http>
|
||||
<remember-me services-ref="rememberMeServices"/>
|
||||
</http>
|
||||
<bean id="rememberMeServices" class=
|
||||
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
|
||||
<property name="userDetailsService" ref="myUserDetailsService"/>
|
||||
<property name="key" value="springRocks"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
[[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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
====
|
||||
|
|
@ -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"]
|
||||
----
|
||||
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
|
||||
<!-- ... -->
|
||||
<property ref="authenticationFailureHandler"/>
|
||||
</bean>
|
||||
|
||||
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
|
||||
<property name="rethrowAuthenticationServiceException" value="true"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
|
||||
<!-- ... -->
|
||||
<property ref="authenticationFailureHandler"/>
|
||||
</bean>
|
||||
|
||||
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
|
||||
<!-- ... -->
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
[[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"]
|
||||
----
|
||||
<http>
|
||||
<remember-me services-ref="rememberMeServices"/>
|
||||
</http>
|
||||
<bean id="rememberMeServices" class=
|
||||
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
|
||||
<property name="userDetailsService" ref="myUserDetailsService"/>
|
||||
<property name="key" value="springRocks"/>
|
||||
<property name="matchingAlgorithm" value="SHA256"/>
|
||||
<property name="encodingAlgorithm" value="SHA256"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<http>
|
||||
<remember-me services-ref="rememberMeServices"/>
|
||||
</http>
|
||||
<bean id="rememberMeServices" class=
|
||||
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
|
||||
<property name="userDetailsService" ref="myUserDetailsService"/>
|
||||
<property name="key" value="springRocks"/>
|
||||
</bean>
|
||||
----
|
||||
====
|
||||
|
||||
== 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.
|
||||
|
|
@ -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, `<websocket-message-broker>` 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"]
|
||||
----
|
||||
<websocket-message-broker use-authorization-manager="true"/>
|
||||
----
|
||||
====
|
||||
|
||||
changes to:
|
||||
|
||||
====
|
||||
.Xml
|
||||
[source,xml,role="primary"]
|
||||
----
|
||||
<websocket-message-broker/>
|
||||
----
|
||||
====
|
||||
|
||||
There are no further migrations steps for Java or Kotlin for this feature.
|
||||
|
||||
== Use `AuthorizationManager` for Request Security
|
||||
|
||||
In 6.0, `<http>` 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"]
|
||||
----
|
||||
<http use-authorization-manager="true" filter-all-dispatcher-types="true"/>
|
||||
----
|
||||
====
|
||||
|
||||
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"]
|
||||
----
|
||||
<http/>
|
||||
----
|
||||
====
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
`once-per-request` applies only when `use-authorization-manager="false"` and `filter-all-dispatcher-types` only applies when `use-authorization-manager="true"`
|
||||
====
|
||||
|
|
@ -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.
|
||||
|
|
@ -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[]
|
||||
Loading…
Reference in New Issue