Loading published curriculum…

16 · Spring Security in depth / LESSON 77 OF 102

UserDetailsService and persistent user accounts

A persistent account store supplies identity and authorities while Spring performs the configured authentication flow.

Before this lesson: Password hashing and credential storage

Understand the topic

UserDetailsService loads account details by login name; it does not authenticate a password by itself. A provider uses the configured password encoder to verify credentials. Represent disabled or locked accounts deliberately rather than treating every existing row as active.

Keep login identifiers normalized under a documented rule and enforce uniqueness in the database. Repository failures must not turn into successful anonymous fallback. Return consistent public login failures so account existence is not unnecessarily disclosed.

EXAMPLE · JAVA

Account lookup sketch

// In a UserDetailsService implementation with injected accountRepository.
public org.springframework.security.core.userdetails.UserDetails loadUserByUsername(String login) {
 var account = accountRepository.findByLogin(login)
  .orElseThrow(() -> new org.springframework.security.core.userdetails.UsernameNotFoundException("Invalid credentials"));
 return org.springframework.security.core.userdetails.User.withUsername(account.login())
  .password(account.passwordHash())
  .authorities(account.authorities().toArray(String[]::new))
  .disabled(!account.enabled()).build();
}

What to expect

Integration sketch: implement the repository and account projection with login, passwordHash, authorities, and enabled fields. Password verification remains the authentication provider’s responsibility.

YOUR TURN

Put it into practice

  1. 01Implement the account repository and UserDetailsService.
  2. 02Test unknown, disabled, valid, and wrong-password accounts through the actual authentication flow.
  3. 03Verify: Only valid enabled accounts authenticate and stored passwords remain encoded.

Pass a quiz or complete a lab to check today’s streak. Each lesson counts once per day, including when you review it later.

UNDER THE HOOD

Build the mental model

A persistent account store supplies identity and authorities while Spring performs the configured authentication flow.

  1. 01UserDetailsService loads account details by login name; it does not authenticate a password by itself. A provider uses the configured password encoder to verify credentials. Represent disabled or locked accounts deliberately rather than treating every existing row as active.
  2. 02Keep login identifiers normalized under a documented rule and enforce uniqueness in the database. Repository failures must not turn into successful anonymous fallback. Return consistent public login failures so account existence is not unnecessarily disclosed.
  3. 03Trace the example: Integration sketch: implement the repository and account projection with login, passwordHash, authorities, and enabled fields. Password verification remains the authentication provider’s responsibility.

A mistake worth avoiding

Returning UserDetails is mistaken for proof that the password was checked.

DEBUGGING ROOM

Something broke. Where do you look?

Returning UserDetails is mistaken for proof that the password was checked.

Before revealing the diagnosis, write down your first investigation step.

CHECK YOUR UNDERSTANDING

Does UserDetailsService normally verify the password itself?

Choose one answer

BUILD IT YOURSELF

Implement the account repository and UserDetailsService.

  1. 1.Implement the account repository and UserDetailsService.
  2. 2.Test unknown, disabled, valid, and wrong-password accounts through the actual authentication flow.
  3. 3.Reproduce this failure, then repair it: Returning UserDetails is mistaken for proof that the password was checked.

Acceptance checklist

Lab completion is your self-report. Knowledge checks do not certify project quality.

RETRIEVE IT FROM MEMORY

Does UserDetailsService normally verify the password itself?

Revisit this lesson in three days after a successful check or lab.

Ready for the next step?

Only valid enabled accounts authenticate and stored passwords remain encoded.

Reading is separate from passing a knowledge check or completing a lab.

Go deeper · official references