For the latest stable version, please use Spring Security 6.3.4!

Authentication Migrations

The following steps relate to changes around how authentication is performed.

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 reference documentation and the API docs for more information.

Use Spring Security 6 defaults for encoding, SHA-256 for encoding and MD5 for matching

  • Java

  • XML

@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;
    }

}
<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 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

  • XML

@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;
    }

}
<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

  • XML

@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;
    }

}
<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 AuthenticationServiceExceptions

AuthenticationFilter propagates AuthenticationServiceExceptions to the AuthenticationEntryPoint. Because AuthenticationServiceExceptions 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 AuthenticationServiceExceptions

To prepare for the 6.0 default, wire AuthenticationFilter instances with a AuthenticationFailureHandler that rethrows AuthenticationServiceExceptions, like so:

  • Java

  • Kotlin

  • Xml

AuthenticationFilter authenticationFilter = new AuthenticationFilter(...);
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...);
handler.setRethrowAuthenticationServiceException(true);
authenticationFilter.setAuthenticationFailureHandler(handler);
val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...)
val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...)
handler.setRethrowAuthenticationServiceException(true)
authenticationFilter.setAuthenticationFailureHandler(handler)
<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>

Opt-out Steps

If rethrowing AuthenticationServiceExceptions gives you trouble, you can set the value to false instead of taking the 6.0 default, like so:

  • Java

  • Kotlin

  • Xml

AuthenticationFilter authenticationFilter = new AuthenticationFilter(...);
AuthenticationEntryPointFailureHandler handler = new AuthenticationEntryPointFailureHandler(...);
handler.setRethrowAuthenticationServiceException(false);
authenticationFilter.setAuthenticationFailureHandler(handler);
val authenticationFilter: AuthenticationFilter = new AuthenticationFilter(...)
val handler: AuthenticationEntryPointFailureHandler = new AuthenticationEntryPointFailureHandler(...)
handler.setRethrowAuthenticationServiceException(false)
authenticationFilter.setAuthenticationFailureHandler(handler)
<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>