Add doc and javadoc for CachingUserDetailsService

Close gh-10914

docs/modules/ROOT/pages/servlet/authentication/passwords/cached.adoc

@@ -0,0 +1,38 @@
+[[servlet-authentication-cached]]
+= CachingUserDetailsService
+
+Spring Security's `CachingUserDetailsService` implements xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[UserDetailsService] offering support for caching authentication.
+
+`CachingUserDetailsService` provides caching support for `UserDetails` by delegating the authentication process to the provided `UserDetailsService`. The result is then stored in a `UserCache` to reduce computation in subsequent calls.
+
+Utilize this class by defining a `@Bean` of it that encapsulates a concrete implementation of `UserDetailsService` and set a `UserCache` to cache authenticated `UserDetails`.
+
+For example:
+
+[source,java]
+----
+@Bean
+public CachingUserDetailsService cachingUserDetailsService(UserDetailsService delegate, UserCache userCache) {
+    CachingUserDetailsService service = new CachingUserDetailsService(delegate);
+    service.setUserCache(userCache);
+    return service;
+}
+----
+
+However, a preferable approach would be to use `@Cacheable` in your `UserDetailsService.loadUserByUsername(String)` implementation to cache `UserDetails` by `username`, reducing boilerplate and setup, especially if you are already using cache in your application.
+
+For example:
+
+[source,java]
+----
+@Service
+public class MyCustomUserDetailsImplementation implements UserDetailsService {
+
+    @Override
+    @Cacheable
+    public UserDetails loadUserByUsername(String username) {
+        // some logic here to get the actual user details
+        return userDetails;
+    }
+}
+----

docs/modules/ROOT/pages/servlet/authentication/passwords/user-details-service.adoc

@@ -2,7 +2,7 @@
 = UserDetailsService
 
 {security-api-url}org/springframework/security/core/userdetails/UserDetailsService.html[`UserDetailsService`] is used by xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] for retrieving a username, a password, and other attributes for authenticating with a username and password.
-Spring Security provides xref:servlet/authentication/passwords/in-memory.adoc#servlet-authentication-inmemory[in-memory] and xref:servlet/authentication/passwords/jdbc.adoc#servlet-authentication-jdbc[JDBC] implementations of `UserDetailsService`.
+Spring Security provides xref:servlet/authentication/passwords/in-memory.adoc#servlet-authentication-inmemory[in-memory], xref:servlet/authentication/passwords/jdbc.adoc#servlet-authentication-jdbc[JDBC], and xref:servlet/authentication/passwords/cached.adoc#servlet-authentication-cached[in-cache] implementations of `UserDetailsService`.
 
 You can define custom authentication by exposing a custom `UserDetailsService` as a bean.
 For example, the following listing customizes authentication, assuming that `CustomUserDetailsService` implements `UserDetailsService`: