[[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`].
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.
