How do you implement a custom user details service in Spring Security?

Introduction
Conclusion

Introduction

In Spring Security, the **UserDetailsService** interface is key to managing authentication. It is responsible for loading user-specific data, including the username, password, roles, and authorities, required for authentication and authorization. Implementing a custom **UserDetailsService** allows you to load user information from a custom data source such as a relational database or an external service. This approach is particularly useful when the default database-backed authentication does not meet your application’s needs.

This guide will explain how to implement a custom **UserDetailsService** in Spring Security, how to retrieve user details from a database, and integrate it into Spring Security configuration.

1. Understanding the `UserDetailsService` Interface

The **UserDetailsService** interface has one method that you need to implement:

**loadUserByUsername()**: This method is used to load user data from a data source based on the username. It returns an instance of **UserDetails**, which contains the user's credentials and authorities (roles/permissions).
**UsernameNotFoundException**: This exception is thrown if the username is not found in the data source.

2. Creating the Custom `UserDetailsService` Implementation

A custom **UserDetailsService** fetches user details from a data source, such as a relational database or an in-memory store, and returns them as a **UserDetails** object. This object is then used by Spring Security for authentication.

Here is an example implementation that retrieves user details from a database.

Example: `CustomUserDetailsService` Implementation

Key Steps in the Example:

**userRepository.findByUsername(username)**: This method fetches user data from the database using the username.
**User.builder()**: This constructs a **UserDetails** object using Spring Security's built-in **User** class. The username, password, and roles are set based on the data retrieved.
**UsernameNotFoundException**: If the user is not found, an exception is thrown to signal that the user authentication has failed.

3. Creating the `UserEntity` Class

The **UserEntity** class represents the user object in the database. It typically includes fields like username, password, and roles.

Example: `UserEntity` Class

Explanation:

**@Entity**: This annotation marks the class as a JPA entity, indicating it is mapped to a table in the database.
**@ElementCollection**: This is used to store simple types like strings (e.g., roles) in a collection. You can use **List<String>** to store the roles as a list of strings.

4. Configuring Spring Security to Use `UserDetailsService`

Now that the **CustomUserDetailsService** is implemented, you need to configure Spring Security to use it during the authentication process.

Example: Spring Security Configuration

Key Points:

**userDetailsService(customUserDetailsService)**: This method tells Spring Security to use your custom UserDetailsService for user authentication.
**formLogin()**: This enables the default login form for authentication.

5. Testing the Custom `UserDetailsService`

After configuring your **CustomUserDetailsService**, you can test it by attempting to log in using a user stored in your database.

Create a user in the database: Insert a user record with a username, password, and roles.
Access a secured URL: Try to access a URL that requires authentication. Spring Security should authenticate the user using the custom UserDetailsService.

6. Enhancing `UserDetailsService` with Additional Features

You can further customize your **UserDetailsService** to handle various use cases, such as:

Loading additional user information: For example, user permissions or custom user fields.
Handling account statuses: You can add custom logic to check if the account is locked, expired, or enabled based on your application's needs.
Using **UserDetails** with custom properties: Instead of using Spring Security’s User class, you can implement your own UserDetails class to store custom attributes.

Conclusion

Implementing a custom **UserDetailsService** in Spring Security is a crucial step when you want to use a custom data source (like a database or external service) for user authentication. By extending the **UserDetailsService** interface and implementing the **loadUserByUsername()** method, you can provide Spring Security with the necessary user details (username, password, roles, etc.) to authenticate users effectively. Integrating this custom service into your Spring Security configuration ensures that the authentication process aligns with your application’s requirements.