mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-11-04 00:28:54 +00:00
245 lines
9.4 KiB
Plaintext
245 lines
9.4 KiB
Plaintext
= Authentication Migrations
|
|
|
|
The following steps relate to changes around how authentication is performed.
|
|
|
|
[[servlet-opt-in-sha256-rememberme]]
|
|
== Use SHA-256 in Remember Me
|
|
|
|
The `TokenBasedRememberMeServices` implementation now supports SHA-256 for the Remember Me token and this is the default in Spring Security 6.
|
|
This change makes the implementation more secure by default since MD5 is already proven to be a weak hashing algorithm and vulnerable against collision attacks and modular differential attacks.
|
|
|
|
The new generated tokens now have the information of which algorithm was used to generate the token and that information is used in order to match it.
|
|
If the algorithm name is not present, then the `matchingAlgorithm` property is used to check the token.
|
|
This allows for a smooth transition from MD5 to SHA-256.
|
|
|
|
To opt into the new Spring Security 6 default to encode the tokens while still being able to decode tokens encoded with MD5, you can set the `encodingAlgorithm` property to SHA-256 and the `matchingAlgorithm` property to MD5.
|
|
See the xref:servlet/authentication/rememberme.adoc#_tokenbasedremembermeservices[reference documentation] and the {security-api-url}org/springframework/security/web/authentication/rememberme/TokenBasedRememberMeServices.html[API docs] for more information.
|
|
|
|
[[servlet-opt-in-sha256-sha256-encoding]]
|
|
.Use Spring Security 6 defaults for encoding, SHA-256 for encoding and MD5 for matching
|
|
====
|
|
.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.MD5);
|
|
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="MD5"/>
|
|
<property name="encodingAlgorithm" value="SHA256"/>
|
|
</bean>
|
|
----
|
|
====
|
|
|
|
At some point, you will want to fully migrate to Spring Security 6 defaults. But how do you know when it is safe to do so?
|
|
Let's suppose that you deployed your application using SHA-256 as the encoding algorithm (as you have done <<servlet-opt-in-sha256-sha256-encoding,here>>) on November 1st, if you have the value for the `tokenValiditySeconds` property set to N days (14 is the default), you can migrate to SHA-256 N days after November 1st (which is November 15th in this example).
|
|
By that time, all the tokens generated with MD5 will have expired.
|
|
|
|
.Use Spring Security 6 defaults, SHA-256 for both encoding and matching
|
|
====
|
|
.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>
|
|
----
|
|
====
|
|
|
|
If you are having problems with the Spring Security 6 defaults, you can explicitly opt into 5.8 defaults using the following configuration:
|
|
|
|
.Use MD5 for both encoding and matching algorithms
|
|
====
|
|
.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.MD5;
|
|
TokenBasedRememberMeServices rememberMe = new TokenBasedRememberMeServices(myKey, userDetailsService, encodingAlgorithm);
|
|
rememberMe.setMatchingAlgorithm(RememberMeTokenAlgorithm.MD5);
|
|
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="MD5"/>
|
|
<property name="encodingAlgorithm" value="MD5"/>
|
|
</bean>
|
|
----
|
|
====
|
|
|
|
== 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.
|
|
|
|
=== Configure `AuthenticationFailureHandler` to rethrow ``AuthenticationServiceException``s
|
|
|
|
To prepare for the 6.0 default, wire `AuthenticationFilter` instances with a `AuthenticationFailureHandler` that rethrows ``AuthenticationServiceException``s, 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>
|
|
----
|
|
====
|
|
|
|
[[servlet-authenticationfailurehandler-opt-out]]
|
|
=== Opt-out Steps
|
|
|
|
If rethrowing ``AuthenticationServiceException``s gives you trouble, you can set the value to false instead of taking the 6.0 default, like so:
|
|
|
|
====
|
|
.Java
|
|
[source,java,role="primary"]
|
|
----
|
|
AuthenticationFilter authenticationFilter = new AuthenticationFilter(...);
|
|
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...);
|
|
handler.setRethrowAuthenticationServiceException(false);
|
|
authenticationFilter.setAuthenticationFailureHandler(handler);
|
|
----
|
|
|
|
.Kotlin
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...)
|
|
val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...)
|
|
handler.setRethrowAuthenticationServiceException(false)
|
|
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="false"/>
|
|
</bean>
|
|
----
|
|
====
|