Custom UserDetailsService Implementation

The Authentication Flow and the Role of UserDetailsService

Before we dive into the code, let's visualize where our new component fits into the Spring Security architecture. When a user tries to log in, Spring Security needs to verify their credentials. The DaoAuthenticationProvider is the component that handles this for database-backed authentication. It doesn't know how to talk to your database directly; instead, it delegates this responsibility to two key interfaces:

1. UserDetailsService: Its only job is to find a user by their username.
2. PasswordEncoder: Its job is to compare the submitted password with the stored, hashed password.

The diagram below illustrates this flow. The AuthenticationProvider uses the UserDetailsService to fetch the user's data and the PasswordEncoder to validate the password.

Understanding UserDetailsService and UserDetails

To integrate our database, we need to implement the UserDetailsService interface. It's a simple yet powerful interface with just one method: loadUserByUsername(String username).

The loadUserByUsername method is expected to return an object that implements the UserDetails interface. UserDetails is the contract Spring Security uses to get all the necessary information about a user, such as their password, their roles (authorities), and whether their account is enabled or locked.

There are two common ways to provide a UserDetails implementation:

1. Have your JPA entity (User) implement the UserDetails interface directly.
2. Create a separate wrapper class that implements UserDetails and contains an instance of your User entity.

We will use the second approach because it promotes better separation of concerns. Your User entity's job is to model database data (persistence), while the wrapper's job is to represent security-specific information for the framework.

The following video provides an excellent walkthrough of creating this wrapper class and the UserDetailsService implementation.

Hands-On: Implementing Database Authentication

Now, let's apply these concepts to your group-manager project.

Step 1: Create the UserDetails Wrapper

First, we'll create a class that adapts our User entity to the UserDetails interface.

1. Create a new package named com.example.groupmanager.security.
2. Inside this package, create a new class named CustomUserDetails.
3. This class will implement the UserDetails interface.

package com.example.groupmanager.security;

import com.example.groupmanager.model.User;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.util.Collection;
import java.util.stream.Collectors;

public class CustomUserDetails implements UserDetails {

    private final User user;

    public CustomUserDetails(User user) {
        this.user = user;
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        // We assume your User entity has a getRoles() method that returns a Collection of Role entities
        // Each Role entity should have a getName() method that returns the role name (e.g., "ADMIN").
        // We must prefix the role name with "ROLE_" for Spring Security's role-based authorization to work.
        return user.getRoles().stream()
                .map(role -> new SimpleGrantedAuthority("ROLE_" + role.getName()))
                .collect(Collectors.toList());
    }

    @Override
    public String getPassword() {
        return user.getPassword();
    }

    @Override
    public String getUsername() {
        return user.getUsername();
    }

    // For simplicity, we'll return true for these.
    // In a real application, you might have columns in your User table for these states.
    @Override
    public boolean isAccountNonExpired() {
        return true;
    }

    @Override
    public boolean isAccountNonLocked() {
        return true;
    }

    @Override
    public boolean isCredentialsNonExpired() {
        return true;
    }

    @Override
    public boolean isEnabled() {
        return true;
    }
}

Note: Make sure your User entity has a getRoles() method that returns a Collection of your Role entities, and that your Role entity has a getName() method.

Step 2: Implement the UserDetailsService

Next, create the service that uses your UserRepository to find a user and wrap it in CustomUserDetails.

1. Create a new class named CustomUserDetailsService in the com.example.groupmanager.service package.
2. This class will implement the UserDetailsService interface and should be annotated with @Service.

package com.example.groupmanager.service;

import com.example.groupmanager.model.User;
import com.example.groupmanager.repository.UserRepository;
import com.example.groupmanager.security.CustomUserDetails;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;

@Service
public class CustomUserDetailsService implements UserDetailsService {

    @Autowired
    private UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        User user = userRepository.findByUsername(username)
                .orElseThrow(() -> new UsernameNotFoundException("User not found with username: " + username));
        
        return new CustomUserDetails(user);
    }
}

By annotating this class with @Service, you make it a Spring bean. Spring Security is smart enough to automatically find any bean of type UserDetailsService in the application context and use it for authentication.

Step 3: Update the Security Configuration

Now, let's update SecurityConfig.java to use our new components and remove the old in-memory setup.

1. Remove the In-Memory UserDetailsService: Delete the userDetailsService() bean method that created the InMemoryUserDetailsManager. Spring will now automatically use your CustomUserDetailsService.

2. Add a PasswordEncoder Bean: The User.withDefaultPasswordEncoder() method we used is deprecated and insecure. Real applications must use a strong, one-way hashing algorithm for passwords. BCrypt is the industry standard and Spring Security's recommended choice.

   Add the following bean to your SecurityConfig.java class:

   import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
   import org.springframework.security.crypto.password.PasswordEncoder;
   
   // Inside the SecurityConfig class
   @Bean
   public PasswordEncoder passwordEncoder() {
       return new BCryptPasswordEncoder();
   }
   

   Just like with the UserDetailsService, Spring Security will automatically detect and use this PasswordEncoder bean.

Step 4: Seed the Database with a Test User

Your database is likely empty, so there's no user to log in with. We need to add at least one user with an encoded password. A great way to do this during development is with a CommandLineRunner, which executes code on application startup.

Let's use this technique to create an "admin" user if one doesn't already exist.

In your main application class (GroupManagerApplication.java), add the following bean. This will create an admin user with the password "password" and an ADMIN role the first time you run the application.

// In GroupManagerApplication.java

import com.example.groupmanager.model.Role;
import com.example.groupmanager.model.User;
import com.example.groupmanager.repository.RoleRepository;
import com.example.groupmanager.repository.UserRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.security.crypto.password.PasswordEncoder;
import java.util.Set;

// Add this bean method inside the main application class
@Bean
CommandLineRunner run(UserRepository userRepository, RoleRepository roleRepository, PasswordEncoder passwordEncoder) {
    return args -> {
        // Only run this logic if you want to create a default admin and role
        // For example, you might check if the admin user already exists
        if (roleRepository.findByName("ADMIN").isEmpty()) {
            Role adminRole = roleRepository.save(new Role("ADMIN"));
            roleRepository.save(new Role("USER")); // Also create a USER role

            User adminUser = new User();
            adminUser.setUsername("admin");
            adminUser.setPassword(passwordEncoder.encode("password"));
            adminUser.setRoles(Set.of(adminRole));
            userRepository.save(adminUser);
        }
    };
}

Note: This assumes you have a Role entity and a corresponding RoleRepository. If you don't, you'll need to create them first based on our lessons from the Spring Data JPA module.

Step 5: Test Your Implementation

You're all set! Restart your application.

1. The CommandLineRunner will execute, creating the ADMIN and USER roles, and an admin user with an encrypted password in your database. You can verify this using your MySQL client.
2. Open Postman and try to access a protected endpoint from the previous lesson, for example, POST /users.
3. In the "Authorization" tab, select "Basic Auth" and enter the username admin and password password.
4. The request should now succeed because Spring Security authenticated your credentials against the data stored in your MySQL database. If you try with incorrect credentials or as a user without the ADMIN role, you should receive a 401 Unauthorized or 403 Forbidden error, respectively.

Conclusion

Congratulations! You have successfully transitioned your application's security from a fragile, in-memory setup to a robust, database-driven authentication system. This is a fundamental skill for any backend developer.

Key Takeaways:

• The UserDetailsService interface is the central component for loading user data from any source.
• The UserDetails interface provides a standard contract for Spring Security to access user credentials, authorities, and account status.
• Using a wrapper class to implement UserDetails is a clean pattern that separates persistence concerns from security concerns.
• Spring Boot's auto-configuration simplifies the process: just provide a UserDetailsService bean and a PasswordEncoder bean, and Spring Security will wire them up.
• Using BCryptPasswordEncoder is essential for securely storing passwords.
• A CommandLineRunner is a convenient tool for seeding your database with initial data during development.

We are now authenticating users against our database using HTTP Basic. However, this method requires sending credentials with every request and is not ideal for modern stateless APIs. In our next lesson, we will address this by building a dedicated login endpoint that generates a JSON Web Token (JWT), paving the way for a secure, token-based authentication scheme.