UserDetailsService implementation in Spring Boot

Introduction

UserDetailsService helps Spring Security find user info to check login details.

When you want to load user info from a database for login.

When you need to check user roles and permissions during login.

When you want to customize how user data is fetched for security.

When you want to connect Spring Security with your own user storage.

When you want to handle login errors if user not found.

Syntax

Spring Boot

public class MyUserDetailsService implements UserDetailsService {
    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        // find user by username
        // if not found, throw exception
        // return UserDetails object with username, password, roles
    }
}

Implement UserDetailsService interface and override loadUserByUsername.

Throw UsernameNotFoundException if user is missing.

Examples

Simple example returning a fixed user if username is 'admin'.

Spring Boot

public class MyUserDetailsService implements UserDetailsService {
    @Override
    public UserDetails loadUserByUsername(String username) {
        if (!username.equals("admin")) {
            throw new UsernameNotFoundException("User not found");
        }
        return User.withUsername("admin")
                   .password("password")
                   .roles("USER")
                   .build();
    }
}

Example fetching user from database using a repository.

Spring Boot

public class MyUserDetailsService implements UserDetailsService {
    private final UserRepository userRepository;

    public MyUserDetailsService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public UserDetails loadUserByUsername(String username) {
        UserEntity user = userRepository.findByUsername(username)
            .orElseThrow(() -> new UsernameNotFoundException("User not found"));
        return User.withUsername(user.getUsername())
                   .password(user.getPassword())
                   .roles(user.getRole())
                   .build();
    }
}

Sample Program

This service checks if the username is 'user1'. If yes, it returns user details with password and role. Otherwise, it throws an error.

Spring Boot

package com.example.security;

import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.core.userdetails.User;
import org.springframework.stereotype.Service;

@Service
public class MyUserDetailsService implements UserDetailsService {

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        if (!"user1".equals(username)) {
            throw new UsernameNotFoundException("User not found: " + username);
        }
        return User.withUsername("user1")
                   .password("{noop}pass123")
                   .roles("USER")
                   .build();
    }
}

Important Notes

Use {noop} prefix in password if you don't want encoding for demo.

Always throw UsernameNotFoundException if user is missing to inform Spring Security.

Use User.withUsername() builder to create UserDetails easily.

Summary

UserDetailsService loads user info for Spring Security login.

Override loadUserByUsername to fetch user data.

Throw exception if user not found to handle login errors.