Improve documentation about CredentialsContainer

Author: chu3la

docs/modules/ROOT/pages/servlet/authentication/architecture.adoc

@@ -117,13 +117,13 @@ However, if you do, take a look at the JavaDoc for `SecurityContextHolder` to le
 [[servlet-authentication-securitycontext]]
 == SecurityContext
 
-The javadoc:org.springframework.security.core.context.SecurityContext[] is obtained from the <<servlet-authentication-securitycontextholder>>.
+The {security-api-url}org/springframework/security/core/context/SecurityContext.html[`SecurityContext`] is obtained from the <<servlet-authentication-securitycontextholder>>.
 The `SecurityContext` contains an <<servlet-authentication-authentication>> object.
 
 [[servlet-authentication-authentication]]
 == Authentication
 
-The javadoc:org.springframework.security.core.Authentication[] interface serves two main purposes within Spring Security:
+The {security-api-url}org/springframework/security/core/Authentication.html[`Authentication`] interface serves two main purposes within Spring Security:
 
 * An input to <<servlet-authentication-authenticationmanager,`AuthenticationManager`>> to provide the credentials a user has provided to authenticate.
 When used in this scenario, `isAuthenticated()` returns `false`.
@@ -141,7 +141,7 @@ Two examples are roles and scopes.
 
 [[servlet-authentication-granted-authority]]
 == GrantedAuthority
-javadoc:org.springframework.security.core.GrantedAuthority[] instances are high-level permissions that the user is granted.
+{security-api-url}org/springframework/security/core/GrantedAuthority.html[`GrantedAuthority`] instances are high-level permissions that the user is granted.
 Two examples are roles and scopes.
 
 You can obtain `GrantedAuthority` instances from the <<servlet-authentication-authentication,`Authentication.getAuthorities()`>> method.
@@ -160,7 +160,7 @@ Of course, Spring Security is expressly designed to handle this common requireme
 [[servlet-authentication-authenticationmanager]]
 == AuthenticationManager
 
-javadoc:org.springframework.security.authentication.AuthenticationManager[] is the API that defines how Spring Security's Filters perform  xref:features/authentication/index.adoc#authentication[authentication].
+{security-api-url}org/springframework/security/authentication/AuthenticationManager.html[`AuthenticationManager`] is the API that defines how Spring Security's Filters perform  xref:features/authentication/index.adoc#authentication[authentication].
 The <<servlet-authentication-authentication,`Authentication`>> that is returned is then set on the <<servlet-authentication-securitycontextholder>> by the controller (that is, by xref:servlet/architecture.adoc#servlet-security-filters[Spring Security's `Filters` instances]) that invoked the `AuthenticationManager`.
 If you are not integrating with Spring Security's `Filters` instances, you can set the `SecurityContextHolder` directly and are not required to use an `AuthenticationManager`.
 
@@ -170,7 +170,7 @@ While the implementation of `AuthenticationManager` could be anything, the most
 [[servlet-authentication-providermanager]]
 == ProviderManager
 
-javadoc:org.springframework.security.authentication.ProviderManager[] is the most commonly used implementation of <<servlet-authentication-authenticationmanager,`AuthenticationManager`>>.
+{security-api-url}org/springframework/security/authentication/ProviderManager.html[`ProviderManager`] is the most commonly used implementation of <<servlet-authentication-authenticationmanager,`AuthenticationManager`>>.
 `ProviderManager` delegates to a `List` of <<servlet-authentication-authenticationprovider,`AuthenticationProvider`>> instances.
 Each `AuthenticationProvider` has an opportunity to indicate that authentication should be successful, fail, or indicate it cannot make a decision and allow a downstream `AuthenticationProvider` to decide.
 If none of the configured `AuthenticationProvider` instances can authenticate, authentication fails with a `ProviderNotFoundException`, which is a special `AuthenticationException` that indicates that the `ProviderManager` was not configured to support the type of `Authentication` that was passed into it.
@@ -195,24 +195,26 @@ image::{figures}/providermanagers-parent.png[]
 By default, `ProviderManager` tries to clear any sensitive credentials information from the `Authentication` object that is returned by a successful authentication request.
 This prevents information, such as passwords, being retained longer than necessary in the `HttpSession`.
 
+> **Note:** The `CredentialsContainer` interface plays a critical role in the authentication process. It allows for the erasure of credential information once it is no longer needed, thereby enhancing security by ensuring sensitive data is not retained longer than necessary.
+
 This may cause issues when you use a cache of user objects, for example, to improve performance in a stateless application.
 If the `Authentication` contains a reference to an object in the cache (such as a `UserDetails` instance) and this has its credentials removed, it is no longer possible to authenticate against the cached value.
 You need to take this into account if you use a cache.
 An obvious solution is to first make a copy of the object, either in the cache implementation or in the `AuthenticationProvider` that creates the returned `Authentication` object.
 Alternatively, you can disable the `eraseCredentialsAfterAuthentication` property on `ProviderManager`.
-See the Javadoc for the javadoc:org.springframework.security.authentication.ProviderManager[] class.
+See the Javadoc for the {security-api-url}org/springframework/security/authentication/ProviderManager.html[ProviderManager] class.
 
 [[servlet-authentication-authenticationprovider]]
 == AuthenticationProvider
 
-You can inject multiple javadoc:org.springframework.security.authentication.AuthenticationProvider[] instances into <<servlet-authentication-providermanager,`ProviderManager`>>.
+You can inject multiple {security-api-url}org/springframework/security/authentication/AuthenticationProvider.html[``AuthenticationProvider``s] instances into <<servlet-authentication-providermanager,`ProviderManager`>>.
 Each `AuthenticationProvider` performs a specific type of authentication.
 For example, xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] supports username/password-based authentication, while `JwtAuthenticationProvider` supports authenticating a JWT token.
 
 [[servlet-authentication-authenticationentrypoint]]
 == Request Credentials with `AuthenticationEntryPoint`
 
-javadoc:org.springframework.security.web.AuthenticationEntryPoint[] is used to send an HTTP response that requests credentials from a client.
+{security-api-url}org/springframework/security/web/AuthenticationEntryPoint.html[`AuthenticationEntryPoint`] is used to send an HTTP response that requests credentials from a client.
 
 Sometimes, a client proactively includes credentials (such as a username and password) to request a resource.
 In these cases, Spring Security does not need to provide an HTTP response that requests credentials from the client, since they are already included.
@@ -229,7 +231,7 @@ The `AuthenticationEntryPoint` implementation might perform a xref:servlet/authe
 [[servlet-authentication-abstractprocessingfilter]]
 == AbstractAuthenticationProcessingFilter
 
-javadoc:org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter[] is used as a base `Filter` for authenticating a user's credentials.
+{security-api-url}org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.html[`AbstractAuthenticationProcessingFilter`] is used as a base `Filter` for authenticating a user's credentials.
 Before the credentials can be authenticated, Spring Security typically requests the credentials by using <<servlet-authentication-authenticationentrypoint,`AuthenticationEntryPoint`>>.
 
 Next, the `AbstractAuthenticationProcessingFilter` can authenticate any authentication requests that are submitted to it.
@@ -245,26 +247,26 @@ image:{icondir}/number_2.png[] Next, the <<servlet-authentication-authentication
 image:{icondir}/number_3.png[] If authentication fails, then __Failure__.
 
 * The <<servlet-authentication-securitycontextholder>> is cleared out.
-* `RememberMeServices.loginFail` is invoked.ƒ
+* `RememberMeServices.loginFail` is invoked.
 If remember me is not configured, this is a no-op.
-See the javadoc:org.springframework.security.web.authentication.rememberme.package-summary[rememberme] package.
+See the {security-api-url}org/springframework/security/web/authentication/rememberme/package-frame.html[`rememberme`] package.
 * `AuthenticationFailureHandler` is invoked.
-See the javadoc:org.springframework.security.web.authentication.AuthenticationFailureHandler[] interface.
+See the {security-api-url}org/springframework/security/web/authentication/AuthenticationFailureHandler.html[`AuthenticationFailureHandler`] interface.
 
 image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
 
 * `SessionAuthenticationStrategy` is notified of a new login.
-See the javadoc:org.springframework.security.web.authentication.session.SessionAuthenticationStrategy[] interface.
+See the {security-api-url}org/springframework/security/web/authentication/session/SessionAuthenticationStrategy.html[`SessionAuthenticationStrategy`] interface.
 * The <<servlet-authentication-authentication>> is set on the <<servlet-authentication-securitycontextholder>>.
 Later, if you need to save the `SecurityContext` so that it can be automatically set on future requests, `SecurityContextRepository#saveContext` must be explicitly invoked.
-See the javadoc:org.springframework.security.web.context.SecurityContextHolderFilter[] class.
+See the {security-api-url}org/springframework/security/web/context/SecurityContextHolderFilter.html[`SecurityContextHolderFilter`] class.
 
 * `RememberMeServices.loginSuccess` is invoked.
 If remember me is not configured, this is a no-op.
-See the javadoc:org.springframework.security.web.authentication.rememberme.package-summary[rememberme] package.
+See the {security-api-url}org/springframework/security/web/authentication/rememberme/package-frame.html[`rememberme`] package.
 * `ApplicationEventPublisher` publishes an `InteractiveAuthenticationSuccessEvent`.
 * `AuthenticationSuccessHandler` is invoked.
-See the javadoc:org.springframework.security.web.authentication.AuthenticationSuccessHandler[] interface.
+See the {security-api-url}org/springframework/security/web/authentication/AuthenticationSuccessHandler.html[`AuthenticationSuccessHandler`] interface.
 
 
 // daoauthenticationprovider (goes in username/password)

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

@@ -0,0 +1,41 @@
+== Password Erasure
+
+After successful authentication, it's a security best practice to erase credentials from memory to prevent them from being exposed to potential memory dump attacks. `ProviderManager` and most `AuthenticationProvider` implementations in Spring Security support this practice through the `eraseCredentials` method, which should be invoked after the authentication process completes.
+
+=== Best Practices
+
+. *Immediate Erasure*: Credentials should be erased immediately after they are no longer needed. This minimizes the window during which the credentials are exposed in memory.
+. *Automatic Erasure*: Configure `ProviderManager` to automatically erase credentials post-authentication by setting `eraseCredentialsAfterAuthentication` to `true`.
+. *Custom Erasure Strategies*: Implement custom erasure strategies in custom `AuthenticationProvider` implementations if the default erasure behavior does not meet specific security requirements.
+
+=== Risk Assessment
+
+Failure to properly erase credentials can lead to several risks:
+
+. *Memory Access Attacks*: Attackers can access raw credentials from memory through exploits like buffer overflow attacks or memory dumps.
+. *Insider Threats*: Malicious insiders with access to systems could potentially extract credentials from application memory.
+. *Accidental Exposure*: In multi-tenant environments, lingering credentials in memory could accidentally be exposed to other tenants.
+
+=== Implementation
+
+[source,java]
+----
+public class CustomAuthenticationProvider extends AbstractUserDetailsAuthenticationProvider {
+    @Override
+    protected void additionalAuthenticationChecks(UserDetails userDetails,
+                                                  UsernamePasswordAuthenticationToken authentication)
+            throws AuthenticationException {
+        // Perform authentication checks
+        if (!passwordEncoder.matches(authentication.getCredentials().toString(), userDetails.getPassword())) {
+            throw new BadCredentialsException(messages.getMessage(
+                "AbstractUserDetailsAuthenticationProvider.badCredentials",
+                "Bad credentials"));
+        }
+
+        // Erase credentials post-check
+        authentication.eraseCredentials();
+    }
+}
+----
+
+By implementing these practices, organizations can significantly enhance the security of their authentication systems by ensuring that credentials are not left exposed in system memory.

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

@@ -1,5 +1,42 @@
 [[servlet-authentication-userdetails]]
 = UserDetails
 
-javadoc:org.springframework.security.core.userdetails.UserDetails[] is returned by the xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`].
+{security-api-url}org/springframework/security/core/userdetails/UserDetails.html[`UserDetails`] is returned by the xref:servlet/authentication/passwords/user-details-service.adoc#servlet-authentication-userdetailsservice[`UserDetailsService`].
 The xref:servlet/authentication/passwords/dao-authentication-provider.adoc#servlet-authentication-daoauthenticationprovider[`DaoAuthenticationProvider`] validates the `UserDetails` and then returns an xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] that has a principal that is the `UserDetails` returned by the configured `UserDetailsService`.
+
+=== Credentials Management
+
+Implementing the `CredentialsContainer` interface in classes that store user credentials, such as those extending or implementing `UserDetails`, is strongly recommended, especially in applications where user details are not cached. This practice enhances security by ensuring that sensitive data, such as passwords, are not retained in memory longer than necessary.
+
+==== When to Implement CredentialsContainer
+
+Applications that do not employ caching mechanisms for `UserDetails` should particularly consider implementing `CredentialsContainer`. This approach helps in mitigating the risk associated with retaining sensitive information in memory, which can be vulnerable to attack vectors such as memory dumps.
+
+[source,java]
+----
+public class MyUserDetails implements UserDetails, CredentialsContainer {
+    private String username;
+    private String password;
+
+    // UserDetails implementation...
+
+    @Override
+    public void eraseCredentials() {
+        this.password = null; // Securely erase the password field
+    }
+}
+----
+
+==== Implementation Guidelines
+
+* *Immediate Erasure*: Credentials should be erased immediately after they are no longer needed, typically post-authentication.
+* *Automatic Invocation*: Ensure that `eraseCredentials()` is automatically called by your authentication framework, such as `AuthenticationManager` or `AuthenticationProvider`, once the authentication process is complete.
+* *Consistency*: Apply this practice uniformly across all applications to prevent security lapses that could lead to data breaches.
+
+==== Beyond Basic Interface Implementation
+
+While interfaces like `CredentialsContainer` provide a framework for credential management, the practical implementation often depends on specific classes and their interactions. For example, the `DaoAuthenticationProvider` class, adhering to the `AuthenticationProvider`'s contract, does not perform credential erasure within its own `authenticate` method.
+
+Instead, it relies on `ProviderManager`—Spring Security's default implementation of `AuthenticationManager`—to handle the erasure of credentials and other sensitive data post-authentication. This separation emphasizes the principle that the authentication process itself should not assume the responsibility for credential management. It is worth noting that the `AuthenticationManager` API documentation specifies that the implementation should return "a fully authenticated object including credentials" via the `authenticate` method, underscoring the distinction between authentication and credential management.
+
+Incorporating `CredentialsContainer` into your `UserDetails` implementation aligns with security best practices, reducing potential exposure to data breaches by minimizing the lifespan of sensitive data in memory.