From 7cbb9e82f9cf097f4634e14a3225e4eea45e3e99 Mon Sep 17 00:00:00 2001 From: Marcus Da Coregio Date: Thu, 27 Oct 2022 15:39:51 -0300 Subject: [PATCH] Document how to opt-in for SHA256 in RememberMe Closes gh-12097 --- docs/modules/ROOT/pages/migration.adoc | 161 +++++++++++++++++++++++++ 1 file changed, 161 insertions(+) diff --git a/docs/modules/ROOT/pages/migration.adoc b/docs/modules/ROOT/pages/migration.adoc index ff2e513910..93f3f166bd 100644 --- a/docs/modules/ROOT/pages/migration.adoc +++ b/docs/modules/ROOT/pages/migration.adoc @@ -1703,6 +1703,167 @@ authenticationFilter.setAuthenticationFailureHandler(handler) ---- ==== +[[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"] +---- + + + + + + + + + + +---- +==== + +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 <>) 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"] +---- + + + + + + + + + + +---- +==== + +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"] +---- + + + + + + + + + + +---- +==== + == Reactive === Use `AuthorizationManager` for Method Security