Skip to content

Commit 616b43f

Browse files
jzheauxjzheaux
committed
Restore 6.x Migration Steps
Issue gh-16873
1 parent 857ef6f commit 616b43f

File tree

8 files changed

+546
-14
lines changed

8 files changed

+546
-14
lines changed

Diff for: ‎docs/modules/ROOT/nav.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
* xref:migration-7/index.adoc[Preparing for 7.0]
66
** xref:migration-7/configuration.adoc[Configuration]
77
** xref:migration-7/ldap.adoc[LDAP]
8-
* xref:migration/index.adoc[Migrating to 6.2]
8+
* xref:migration/index.adoc[Migrating to 6]
99
** xref:migration/authorization.adoc[Authorization Changes]
1010
* xref:getting-spring-security.adoc[Getting Spring Security]
1111
* xref:features/index.adoc[Features]

Diff for: ‎docs/modules/ROOT/pages/migration/index.adoc

+25-13
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,35 @@
11
[[migration]]
2-
= Migrating to 6.2
2+
= Migrating to 6.0
33
:spring-security-reference-base-url: https://docs.spring.io/spring-security/reference
44

5-
This guide provides instructions for migrating from Spring Security 6.1 to Spring Security 6.2.
5+
The Spring Security team has prepared the 5.8 release to simplify upgrading to Spring Security 6.0.
6+
Use 5.8 and
7+
ifdef::spring-security-version[]
8+
{spring-security-reference-base-url}/5.8/migration/index.html[its preparation steps]
9+
endif::[]
10+
ifndef::spring-security-version[]
11+
its preparation steps
12+
endif::[]
13+
to simplify updating to 6.0.
614

7-
== Update to Spring Security 6.2
15+
After updating to 5.8, follow this guide to perform any remaining migration or cleanup steps.
816

9-
When updating to a new minor version, it is important that you are already using the latest patch release of the previous minor version.
10-
For example, if you are upgrading to Spring Security 6.2, you should already be using the latest patch release of Spring Security 6.1.
11-
This makes it easier to identify any changes that may have been introduced in the new minor version.
17+
And recall that if you run into trouble, the preparation guide includes opt-out steps to revert to 5.x behaviors.
1218

13-
Therefore, the first step is to ensure you are on the latest patch release of Spring Boot 3.1.
14-
Next, you should ensure you are on the latest patch release of Spring Security 6.1.
15-
Typically, the latest patch release of Spring Boot uses the latest patch release of Spring Security.
19+
== Update to Spring Security 6
1620

17-
With those two steps complete, you can now update to Spring Security 6.2.
21+
The first step is to ensure you are the latest patch release of Spring Boot 3.0.
22+
Next, you should ensure you are on the latest patch release of Spring Security 6.
23+
For directions, on how to update to Spring Security 6 visit the xref:getting-spring-security.adoc[] section of the reference guide.
1824

19-
== Quick Reference
25+
== Update Package Names
2026

21-
The following list provide a quick reference for the changes that are described in this guide.
27+
Now that you are updated, you need to change your `javax` imports to `jakarta` imports.
2228

23-
- xref:migration/authorization.adoc#compile-with-parameters[You are using method parameter names in `@PreAuthorize`, `@PostAuthorize`, or any other method security annotations]
29+
== Compile With `--parameters`
30+
31+
If you are using method parameter names in `@PreAuthorize`, `@PostAuthorize`, or any other method security annotations, you may need to xref:migration/servlet/authorization.adoc#compile-with-parameters[compile with `-parameters`].
32+
33+
== Perform Application-Specific Steps
34+
35+
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 for: ‎docs/modules/ROOT/pages/migration/reactive.adoc

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
= Reactive
2+
3+
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.
4+
5+
== Use `AuthorizationManager` for Method Security
6+
7+
In 6.0, `@EnableReactiveMethodSecurity` defaults `useAuthorizationManager` to `true`.
8+
So, to complete migration, {security-api-url}org/springframework/security/config/annotation/method/configuration/EnableReactiveMethodSecurity.html[`@EnableReactiveMethodSecurity`] remove the `useAuthorizationManager` attribute:
9+
10+
[tabs]
11+
======
12+
Java::
13+
+
14+
[source,java,role="primary"]
15+
----
16+
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
17+
----
18+
19+
Kotlin::
20+
+
21+
[source,kotlin,role="secondary"]
22+
----
23+
@EnableReactiveMethodSecurity(useAuthorizationManager = true)
24+
----
25+
======
26+
27+
changes to:
28+
29+
[tabs]
30+
======
31+
Java::
32+
+
33+
[source,java,role="primary"]
34+
----
35+
@EnableReactiveMethodSecurity
36+
----
37+
38+
Kotlin::
39+
+
40+
[source,kotlin,role="secondary"]
41+
----
42+
@EnableReactiveMethodSecurity
43+
----
44+
======
45+
46+
== Propagate ``AuthenticationServiceException``s
47+
48+
{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`].
49+
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.
50+
51+
So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` too `true`, you can now remove it like so:
52+
53+
[tabs]
54+
======
55+
Java::
56+
+
57+
[source,java,role="primary"]
58+
----
59+
AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint);
60+
bearerFailureHandler.setRethrowAuthenticationServiceException(true);
61+
AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint);
62+
basicFailureHandler.setRethrowAuthenticationServiceException(true);
63+
----
64+
65+
Kotlin::
66+
+
67+
[source,kotlin,role="secondary"]
68+
----
69+
val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint)
70+
bearerFailureHandler.setRethrowAuthenticationServiceException(true)
71+
val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint)
72+
basicFailureHandler.setRethrowAuthenticationServiceException(true)
73+
----
74+
======
75+
76+
changes to:
77+
78+
[tabs]
79+
======
80+
Java::
81+
+
82+
[source,java,role="primary"]
83+
----
84+
AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint);
85+
AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint);
86+
----
87+
88+
Kotlin::
89+
+
90+
[source,kotlin,role="secondary"]
91+
----
92+
val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint)
93+
val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint)
94+
----
95+
======
96+
97+
[NOTE]
98+
====
99+
If you configured the `ServerAuthenticationFailureHandler` only for the purpose of updating to 6.0, you can remove it completely.
100+
====

Diff for: ‎docs/modules/ROOT/pages/migration/servlet/authentication.adoc

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
= Authentication Migrations
2+
3+
The following steps relate to how to finish migrating authentication support.
4+
5+
== Propagate ``AuthenticationServiceException``s
6+
7+
{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/web/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`].
8+
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.
9+
10+
So, if you opted into this behavior by setting `rethrowAuthenticationServiceException` to `true`, you can now remove it like so:
11+
12+
[tabs]
13+
======
14+
Java::
15+
+
16+
[source,java,role="primary"]
17+
----
18+
AuthenticationFilter authenticationFilter = new AuthenticationFilter(...);
19+
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...);
20+
handler.setRethrowAuthenticationServiceException(true);
21+
authenticationFilter.setAuthenticationFailureHandler(handler);
22+
----
23+
24+
Kotlin::
25+
+
26+
[source,kotlin,role="secondary"]
27+
----
28+
val authenticationFilter: AuthenticationFilter = AuthenticationFilter(...)
29+
val handler: AuthenticationEntryPointFailureHandler = AuthenticationEntryPointFailureHandler(...)
30+
handler.setRethrowAuthenticationServiceException(true)
31+
authenticationFilter.setAuthenticationFailureHandler(handler)
32+
----
33+
34+
Xml::
35+
+
36+
[source,xml,role="secondary"]
37+
----
38+
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
39+
<!-- ... -->
40+
<property ref="authenticationFailureHandler"/>
41+
</bean>
42+
43+
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
44+
<property name="rethrowAuthenticationServiceException" value="true"/>
45+
</bean>
46+
----
47+
======
48+
49+
changes to:
50+
51+
[tabs]
52+
======
53+
Java::
54+
+
55+
[source,java,role="primary"]
56+
----
57+
AuthenticationFilter authenticationFilter = new AuthenticationFilter(...);
58+
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...);
59+
authenticationFilter.setAuthenticationFailureHandler(handler);
60+
----
61+
62+
Kotlin::
63+
+
64+
[source,kotlin,role="secondary"]
65+
----
66+
val authenticationFilter: AuthenticationFilter = AuthenticationFilter(...)
67+
val handler: AuthenticationEntryPointFailureHandler = AuthenticationEntryPointFailureHandler(...)
68+
authenticationFilter.setAuthenticationFailureHandler(handler)
69+
----
70+
71+
Xml::
72+
+
73+
[source,xml,role="secondary"]
74+
----
75+
<bean id="authenticationFilter" class="org.springframework.security.web.authentication.AuthenticationFilter">
76+
<!-- ... -->
77+
<property ref="authenticationFailureHandler"/>
78+
</bean>
79+
80+
<bean id="authenticationFailureHandler" class="org.springframework.security.web.authentication.AuthenticationEntryPointFailureHandler">
81+
<!-- ... -->
82+
</bean>
83+
----
84+
======
85+
86+
[[servlet-opt-in-sha256-rememberme]]
87+
== Use SHA-256 in Remember Me
88+
89+
In 6.0, the `TokenBasedRememberMeServices` uses SHA-256 to encode and match the token.
90+
To complete the migration, any default values can be removed.
91+
92+
For example, if you opted in to the 6.0 default for `encodingAlgorithm` and `matchingAlgorithm` like so:
93+
94+
[tabs]
95+
======
96+
Java::
97+
+
98+
[source,java,role="primary"]
99+
----
100+
@Configuration
101+
@EnableWebSecurity
102+
public class SecurityConfig {
103+
@Bean
104+
SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception {
105+
http
106+
// ...
107+
.rememberMe((remember) -> remember
108+
.rememberMeServices(rememberMeServices)
109+
);
110+
return http.build();
111+
}
112+
@Bean
113+
RememberMeServices rememberMeServices(UserDetailsService userDetailsService) {
114+
RememberMeTokenAlgorithm encodingAlgorithm = RememberMeTokenAlgorithm.SHA256;
115+
TokenBasedRememberMeServices rememberMe = new TokenBasedRememberMeServices(myKey, userDetailsService, encodingAlgorithm);
116+
rememberMe.setMatchingAlgorithm(RememberMeTokenAlgorithm.SHA256);
117+
return rememberMe;
118+
}
119+
}
120+
----
121+
122+
XML::
123+
+
124+
[source,xml,role="secondary"]
125+
----
126+
<http>
127+
<remember-me services-ref="rememberMeServices"/>
128+
</http>
129+
<bean id="rememberMeServices" class=
130+
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
131+
<property name="userDetailsService" ref="myUserDetailsService"/>
132+
<property name="key" value="springRocks"/>
133+
<property name="matchingAlgorithm" value="SHA256"/>
134+
<property name="encodingAlgorithm" value="SHA256"/>
135+
</bean>
136+
----
137+
======
138+
139+
then the defaults can be removed:
140+
141+
[tabs]
142+
======
143+
Java::
144+
+
145+
[source,java,role="primary"]
146+
----
147+
@Configuration
148+
@EnableWebSecurity
149+
public class SecurityConfig {
150+
@Bean
151+
SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception {
152+
http
153+
// ...
154+
.rememberMe((remember) -> remember
155+
.rememberMeServices(rememberMeServices)
156+
);
157+
return http.build();
158+
}
159+
@Bean
160+
RememberMeServices rememberMeServices(UserDetailsService userDetailsService) {
161+
return new TokenBasedRememberMeServices(myKey, userDetailsService);
162+
}
163+
}
164+
----
165+
166+
XML::
167+
+
168+
[source,xml,role="secondary"]
169+
----
170+
<http>
171+
<remember-me services-ref="rememberMeServices"/>
172+
</http>
173+
<bean id="rememberMeServices" class=
174+
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
175+
<property name="userDetailsService" ref="myUserDetailsService"/>
176+
<property name="key" value="springRocks"/>
177+
</bean>
178+
----
179+
======
180+
181+
== Default authorities for oauth2Login()
182+
183+
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`.
184+
185+
In Spring Security 6, the default authority given to a user authenticating with an OAuth2 provider is `OAUTH2_USER`.
186+
The default authority given to a user authenticating with an OpenID Connect 1.0 provider is `OIDC_USER`.
187+
If you configured the `GrantedAuthoritiesMapper` only for the purpose of updating to 6.0, you can remove it completely.

0 commit comments

Comments
 (0)