Outdated Remember-Me documentation for Spring Security 7.x.x – deprecated APIs and unclear persistence distinctions

[balantaim]

Description

Spring Security version: 7.x.x (tested with 7.0.0+)
Documentation page: https://docs.spring.io/spring-security/reference/servlet/authentication/rememberme.html
Current Spring boot version: 4.0.2

Problem

The Remember-Me Authentication → Persistent Token Approach → TokenBasedRememberMeServices documentation contains examples that no longer compile or rely on deprecated APIs in Spring Security 7.0.0+.

Documented example 1:

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http, RememberMeServices rememberMeServices) throws Exception {
	http
			.authorizeHttpRequests((authorize) -> authorize
					.anyRequest().authenticated()
			)
			.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;
}

Example 2: Uses no-arg constructors and setters (deprecated in 7.0.0)

@Bean
RememberMeAuthenticationFilter rememberMeFilter() {
    RememberMeAuthenticationFilter rememberMeFilter = new RememberMeAuthenticationFilter();
    rememberMeFilter.setRememberMeServices(rememberMeServices());
    rememberMeFilter.setAuthenticationManager(theAuthenticationManager);
    return rememberMeFilter;
}

@Bean
TokenBasedRememberMeServices rememberMeServices() {
    TokenBasedRememberMeServices rememberMeServices = new TokenBasedRememberMeServices();
    rememberMeServices.setUserDetailsService(myUserDetailsService);
    rememberMeServices.setKey("springRocks");
    return rememberMeServices;
}

@Bean
RememberMeAuthenticationProvider rememberMeAuthenticationProvider() {
    RememberMeAuthenticationProvider rememberMeAuthenticationProvider = new RememberMeAuthenticationProvider();
    rememberMeAuthenticationProvider.setKey("springRocks");
    return rememberMeAuthenticationProvider;
}

Current (working) approach in Spring Security 7.x.x. Due to deprecations, constructor-based configuration is now required.

Example working configuration:

@Bean
RememberMeAuthenticationFilter rememberMeFilter(
        AuthenticationManager authenticationManager,
        RememberMeServices rememberMeServices
) {
    return new RememberMeAuthenticationFilter(authenticationManager, rememberMeServices);
}

@Bean
TokenBasedRememberMeServices rememberMeServices(
        UserService userDetailsService,
        @Value("${security.remember-me.key}") String REMEMBER_ME_KEY
) {
    return new TokenBasedRememberMeServices(REMEMBER_ME_KEY, userDetailsService);
}

@Bean
RememberMeAuthenticationProvider rememberMeAuthenticationProvider(
        @Value("${security.remember-me.key}") String REMEMBER_ME_KEY
) {
    return new RememberMeAuthenticationProvider(REMEMBER_ME_KEY);
}

Note / Recommendation: clarify persistence vs non-persistence of remember-me tokens

While the documentation describes the persistent_logins table under the Persistent Token Approach, it later presents examples using TokenBasedRememberMeServices without clearly emphasizing that this implementation does not persist tokens to the database and relies solely on cookies.

To reduce confusion, the documentation should explicitly clarify that:

TokenBasedRememberMeServices is a stateless, cookie-based implementation and does not use the persistent_logins table

Database-backed persistence requires PersistentTokenBasedRememberMeServices together with a PersistentTokenRepository

The persistent_logins table applies only to the persistent token implementation, not to TokenBasedRememberMeServices

Making this distinction explicit would help prevent misconfiguration and incorrect assumptions about token storage when following the provided examples.