diff --git a/docs/modules/ROOT/pages/migration.adoc b/docs/modules/ROOT/pages/migration.adoc
index f4cd6ab6ac..612fe46e24 100644
--- a/docs/modules/ROOT/pages/migration.adoc
+++ b/docs/modules/ROOT/pages/migration.adoc
@@ -219,6 +219,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