Spring Security Manual Authentication: A Senior Dev's Guide

You're building a SaaS billing system. Users log in via a custom form, but you need to validate credentials against a legacy CRM and then issue a JWT. Spring Security's auto-config doesn't cut it—you need manual control. This is where manual authentication shines.

Most tutorials show you how to use Spring Security's auto-configuration with a login form. That's fine for demos. In production, you'll need to authenticate users manually—especially when integrating with external systems, supporting multiple authentication sources, or building a REST API.

In this guide, I'll show you how to implement manual authentication in Spring Security 6.2. We'll cover the core components: AuthenticationManager, AuthenticationProvider, and SecurityContextHolder. You'll see real code, production pitfalls, and debugging techniques I've learned from years of building secure systems.

By the end, you'll be able to implement custom login flows that are secure, testable, and maintainable. No more fighting with auto-config.

Understanding the Authentication Architecture

Before writing code, you need to understand Spring Security's authentication architecture. It's a chain of components:

• AuthenticationFilter: Intercepts the request and extracts credentials.
• AuthenticationManager: The orchestrator that delegates to providers.
• AuthenticationProvider: Contains the actual logic to validate credentials.
• SecurityContextHolder: Stores the authenticated principal for the request.

In manual authentication, you bypass the filter chain and directly interact with AuthenticationManager. This gives you full control.

Here's the flow: 1. You create an Authentication object (usually UsernamePasswordAuthenticationToken). 2. You call AuthenticationManager.authenticate(token). 3. The manager delegates to a matching AuthenticationProvider. 4. If successful, you get back a fully populated Authentication object. 5. You set it in SecurityContextHolder.

This pattern is used in REST APIs where you authenticate once and return a token (JWT) that the client sends on subsequent requests.

I've seen teams overcomplicate this by writing their own authentication logic from scratch. Don't. Spring Security's AuthenticationManager is well-tested and handles edge cases you'll miss.

import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Service;

@Service
public class ManualAuthenticationService {

    private final AuthenticationManager authenticationManager;

    public ManualAuthenticationService(AuthenticationManager authenticationManager) {
        this.authenticationManager = authenticationManager;
    }

    public Authentication authenticate(String username, String password) {
        UsernamePasswordAuthenticationToken token = 
            new UsernamePasswordAuthenticationToken(username, password);
        Authentication authentication = authenticationManager.authenticate(token);
        SecurityContextHolder.getContext().setAuthentication(authentication);
        return authentication;
    }
}

Configuring AuthenticationManager Bean

To use manual authentication, you need to provide an AuthenticationManager bean. In Spring Security 6.2, the common approach is to define an AuthenticationConfiguration and expose the manager.

Here's the configuration:

```java @Configuration @EnableWebSecurity public class SecurityConfig {

@Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .requestMatchers("/api/auth/**").permitAll() .anyRequest().authenticated() ) .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .csrf(csrf -> csrf.disable()); return http.build(); }

@Bean public AuthenticationManager authenticationManager( AuthenticationConfiguration authConfig) throws Exception { return authConfig.getAuthenticationManager(); } } ```

I prefer this over using AuthenticationManagerBuilder because it's cleaner and leverages the auto-configuration.

One gotcha: if you have multiple AuthenticationProvider beans, they are automatically picked up by the AuthenticationManager. But if you need a specific order, use @Order or manually build the manager with ProviderManager.

What the docs don't tell you: If you declare your own AuthenticationManager bean, Spring Boot's auto-configuration will back off. You'll lose the default providers. Always ensure you're not accidentally overriding the bean.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/auth/**").permitAll()
                .anyRequest().authenticated()
            )
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .csrf(csrf -> csrf.disable());
        return http.build();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration authConfig) throws Exception {
        return authConfig.getAuthenticationManager();
    }
}

Implementing a Custom AuthenticationProvider

The AuthenticationProvider is where you put your custom authentication logic. For example, validating credentials against a legacy CRM or an LDAP server.

Here's a custom provider that checks credentials against a database:

```java @Component public class DatabaseAuthenticationProvider implements AuthenticationProvider {

private final UserDetailsService userDetailsService; private final PasswordEncoder passwordEncoder;

public DatabaseAuthenticationProvider(UserDetailsService userDetailsService, PasswordEncoder passwordEncoder) { this.userDetailsService = userDetailsService; this.passwordEncoder = passwordEncoder; }

@Override public Authentication authenticate(Authentication authentication) throws AuthenticationException { String username = authentication.getName(); String password = authentication.getCredentials().toString();

UserDetails user = userDetailsService.loadUserByUsername(username);

if (!passwordEncoder.matches(password, user.getPassword())) { throw new BadCredentialsException("Bad credentials"); }

if (!user.isEnabled()) { throw new DisabledException("User disabled"); }

return new UsernamePasswordAuthenticationToken( user, password, user.getAuthorities()); }

@Override public boolean supports(Class<?> authentication) { return UsernamePasswordAuthenticationToken.class .isAssignableFrom(authentication); } } ```

Notice the supports() method. It tells Spring Security which Authentication type this provider handles. If you forget it, your provider won't be called.

Production insight: Always check for isEnabled(), isAccountNonLocked(), etc. I've debugged cases where a locked account was still able to authenticate because the provider only checked the password.

import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.DisabledException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Component;

@Component
public class DatabaseAuthenticationProvider implements AuthenticationProvider {

    private final UserDetailsService userDetailsService;
    private final PasswordEncoder passwordEncoder;

    public DatabaseAuthenticationProvider(UserDetailsService userDetailsService, 
                                           PasswordEncoder passwordEncoder) {
        this.userDetailsService = userDetailsService;
        this.passwordEncoder = passwordEncoder;
    }

    @Override
    public Authentication authenticate(Authentication authentication) 
            throws AuthenticationException {
        String username = authentication.getName();
        String password = authentication.getCredentials().toString();

        UserDetails user = userDetailsService.loadUserByUsername(username);

        if (!passwordEncoder.matches(password, user.getPassword())) {
            throw new BadCredentialsException("Bad credentials");
        }

        if (!user.isEnabled()) {
            throw new DisabledException("User disabled");
        }

        return new UsernamePasswordAuthenticationToken(
            user, password, user.getAuthorities());
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return UsernamePasswordAuthenticationToken.class
            .isAssignableFrom(authentication);
    }
}

Handling Authentication Exceptions

Authentication exceptions like BadCredentialsException and LockedException need to be handled properly. In a REST API, you typically return a 401 with a JSON error body.

You can customize the response using a custom AuthenticationEntryPoint:

```java @Component public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

@Override public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException { response.setContentType("application/json;charset=UTF-8"); response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); String errorMessage = "Authentication failed: " + authException.getMessage(); response.getWriter().write("{\"error\":\"" + errorMessage + "\"}"); } } ```

Then register it in your security config:

``java .exceptionHandling(exceptions -> exceptions .authenticationEntryPoint(customAuthenticationEntryPoint) ) ``

What the official docs won't tell you: The AuthenticationEntryPoint is only invoked for authentication exceptions. For access denied (authorization) exceptions, you need a separate AccessDeniedHandler. Many developers confuse the two.

Also, if you're using JWT, you might want to return different error messages for expired tokens vs. invalid tokens. I've seen teams expose too much information in error messages, which can aid attackers. Keep error messages generic, but log the details server-side.

import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        String errorMessage = "Authentication failed: " + authException.getMessage();
        response.getWriter().write("{\"error\":\"" + errorMessage + "\"}");
    }
}

What the Official Docs Won't Tell You

I've been using Spring Security for over a decade. Here are the hard-learned truths:

1. SecurityContextHolder Strategy is Global, Not Per-Request

Many developers assume the strategy (e.g., MODE_INHERITABLETHREADLOCAL) can be set per request. It can't. It's a JVM-wide setting. If you set it in one filter, it affects the entire application. The only safe way is to set it once at application startup.

2. AuthenticationManager Bean Override Pitfalls

If you define your own AuthenticationManager bean, Spring Boot's auto-configuration will not create the default one. This means you lose all default providers (like the one for in-memory users). Always explicitly add your providers if you override.

3. Exception Handling in Filters

The AuthenticationEntryPoint only handles exceptions thrown during authentication. If your filter chain is misconfigured, you might get exceptions that bypass the entry point. Always test with a misconfigured filter to see the actual response.

4. Stateless vs Stateful Session Management

If you're using manual authentication for a REST API, set session creation policy to STATELESS. Otherwise, Spring Security will create a session even if you don't need one. This can lead to unexpected behavior with CSRF and session fixation.

5. Thread Safety of SecurityContextHolder

By default, SecurityContextHolder uses ThreadLocal. If you spawn new threads, the security context is not propagated. Use MODE_INHERITABLETHREADLOCAL or wrap tasks with DelegatingSecurityContextRunnable. I've seen production outages because of this.

6. Testing Manual Authentication

Testing manual authentication requires mocking AuthenticationManager and verifying SecurityContextHolder. Use SecurityContextHolderTestExecutionListener in Spring Boot tests to clear the context after each test.

These are the gotchas that will save you hours of debugging.

import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;

@Component
public class SecurityContextConfig {

    @PostConstruct
    public void init() {
        SecurityContextHolder.setStrategyName(
            SecurityContextHolder.MODE_INHERITABLETHREADLOCAL);
    }
}

Integrating with JWT Token Generation

In many projects, manual authentication is used to generate a JWT token that the client sends on subsequent requests. Here's how it fits together:

1. User sends username/password to /api/auth/login.
2. Your service calls AuthenticationManager.authenticate().
3. If successful, generate a JWT and return it.
4. On subsequent requests, a filter extracts the JWT and sets the security context.

Here's a simplified login endpoint:

```java @RestController @RequestMapping("/api/auth") public class AuthController {

private final ManualAuthenticationService authService; private final JwtTokenProvider tokenProvider;

public AuthController(ManualAuthenticationService authService, JwtTokenProvider tokenProvider) { this.authService = authService; this.tokenProvider = tokenProvider; }

@PostMapping("/login") public ResponseEntity<JwtResponse> login(@RequestBody LoginRequest request) { Authentication authentication = authService.authenticate( request.getUsername(), request.getPassword()); String token = tokenProvider.generateToken(authentication); return ResponseEntity.ok(new JwtResponse(token)); } } ```

Production insight: Never store the Authentication object in the session for a JWT-based API. The client should send the token with each request. If you store the context in the session, you defeat the purpose of stateless authentication.

Also, ensure your JWT filter sets SecurityContextHolder with the token's authentication. Otherwise, the request will be unauthenticated.

import org.springframework.http.ResponseEntity;
import org.springframework.security.core.Authentication;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    private final ManualAuthenticationService authService;
    private final JwtTokenProvider tokenProvider;

    public AuthController(ManualAuthenticationService authService, 
                          JwtTokenProvider tokenProvider) {
        this.authService = authService;
        this.tokenProvider = tokenProvider;
    }

    @PostMapping("/login")
    public ResponseEntity<JwtResponse> login(@RequestBody LoginRequest request) {
        Authentication authentication = authService.authenticate(
            request.getUsername(), request.getPassword());
        String token = tokenProvider.generateToken(authentication);
        return ResponseEntity.ok(new JwtResponse(token));
    }
}