Spring Security Form-Based & HTTP Basic Authentication

Spring Security ships with two built-in authentication mechanisms: form-based login that mimics the traditional web login page flow, and HTTP Basic, a lightweight scheme embedded directly in the HTTP headers. Both are straightforward to set up, but they behave very differently once credentials leave the browser.

This guide cuts through the documentation and gets into the practical differences. When does each approach make sense? How does the filter chain actually process credentials? Where do things go wrong in production?

When to Use Form-Based Login

Form-based login works well in traditional web applications where users interact through a browser. Session state lives server-side, the browser handles cookies naturally, and you get a branded login page with full control over the user experience.

Use form-based login when your app serves HTML from the server or when you need fine-grained control over session timeout, remember-me functionality, and CSRF handling. It integrates directly with Spring Security’s filter chain.

Skip it for SPAs that consume APIs. The redirect-to-login, process-credentials, redirect-back flow adds round-trips that become noise when your frontend manages its own routing.

When to Use HTTP Basic Authentication

HTTP Basic authentication sends credentials with every request, encoded in the Authorization header. No login page, no redirect, no session cookie. The username and password travel Base64-encoded with each request, so HTTPS is mandatory.

This scheme fits machine-to-machine communication, non-browser API clients, and situations where you want to avoid server-side session state. curl, Postman, or a backend service calling your microservices can authenticate without managing cookies or tokens.

Skip it for browser-based web apps. A native browser authentication dialog feels outdated and delivers a poor experience. Credentials also travel with every request, which increases exposure if HTTPS is misconfigured.

Authentication Flow Comparison

The filter chain handles each mechanism very differently. Here is what happens under the hood.

graph TD
    A[Client Request] --> B{Authentication Type?}
    B -->|Form Login| C[UsernamePasswordAuthenticationFilter]
    B -->|HTTP Basic| D[BasicAuthenticationFilter]
    C --> E[Login Page GET /login]
    C --> F[Credential POST /login]
    F --> G{Valid Credentials?}
    G -->|Yes| H[SecurityContext Created]
    G -->|No| I[AuthenticationFailureHandler]
    D --> J{HTTP Header Present?}
    J -->|Yes| K[Extract & Decode Credentials]
    J -->|No| L[WWW-Authenticate Header Sent]
    K --> M{Valid Credentials?}
    M -->|Yes| N[SecurityContext Created]
    M -->|No| O[401 Unauthorized]
    H --> P[Session Created]
    P --> Q[Redirect to Saved URL]
    N --> R[No Session Created]
    R --> S[Response with Resource]
    I --> T[Redirect to /login?error]

Form login creates a session after successful authentication and stores the SecurityContext in the HTTP session. Subsequent requests use the session cookie to restore authentication without re-entering credentials. HTTP Basic reconstructs authentication from the request header on each call, meaning there is no session to manage or timeout.

Failure Scenarios

Both mechanisms fail differently. Knowing what happens when things break is essential for building proper monitoring and user feedback.

Session Fixation

Session fixation attacks exploit the way sessions are created and transferred. An attacker creates a session, tricks a victim into logging in using that same session identifier, and then hijacks the authenticated session. Spring Security protects against this by creating a new session ID after authentication when using form login. HTTP Basic does not use sessions at all, sidestepping this class of attack entirely. With form login, keep sessionFixation().migrateSession() enabled, which is the default.

CSRF on Login

Cross-Site Request Forgery on login is an often-overlooked attack vector. An attacker can craft a login request from a victim’s browser to your site using the victim’s credentials. If CSRF protection is absent from the login form, the victim ends up authenticated as the attacker, potentially exposing data to the wrong session. Spring Security applies CSRF tokens to state-changing operations by default, including form submissions. The login form must include the CSRF token in a hidden field. The token value comes from the CsrfToken request attribute.

Brute Force Attacks

Both mechanisms are vulnerable to credential stuffing and brute force attacks without additional protection. Failed login attempts need rate limiting, temporary account lockouts, or CAPTCHA challenges to prevent automated attacks. Spring Security does not include these protections built into the core framework, so you typically implement them as a custom AuthenticationFailureHandler or delegate to a library like Bucket4j with a Servlet filter. Account takeover protection requires tracking failed attempts by IP and username, with exponential backoff on repeated failures.

Trade-Off Comparison

Each authentication mechanism makes different trade-offs around session management, client compatibility, security posture, and operational complexity.

Form login and session-based authentication share the same session management concerns. Token-based approaches like JWT remove server-side state but shift complexity to token validation and revocation. OAuth2 adds an authorization server, token endpoint, and client registration to your architecture.

Implementation

Setting up both mechanisms requires a Spring Security configuration class and knowing which components participate in the filter chain.

Form Login Configuration

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/login", "/css/**", "/error").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginPage("/login")
                .loginProcessingUrl("/login")
                .defaultSuccessUrl("/dashboard", true)
                .failureUrl("/login?error=true")
                .permitAll()
            )
            .logout(logout -> logout
                .logoutUrl("/logout")
                .logoutSuccessUrl("/login?logout=true")
                .invalidateHttpSession(true)
                .deleteCookies("JSESSIONID")
            )
            .sessionManagement(session -> session
                .sessionFixation().migrateSession()
                .maximumSessions(1)
                .maxSessionsPreventsLogin(false)
            );

        return http.build();
    }

    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user = User.builder()
            .username("user")
            .password(passwordEncoder().encode("password"))
            .roles("USER")
            .build();

        UserDetails admin = User.builder()
            .username("admin")
            .password(passwordEncoder().encode("admin123"))
            .roles("USER", "ADMIN")
            .build();

        return new InMemoryUserDetailsManager(user, admin);
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

The configuration chains together several decisions. authorizeHttpRequests declares which paths are public and which require authentication. formLogin() customizes the login page URL, the processing endpoint, success handling, and failure redirect. The logout block invalidates the session and clears cookies.

HTTP Basic Configuration

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/health", "/info").permitAll()
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults())
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            );

        return http.build();
    }
}

httpBasic() activates the BasicAuthenticationFilter for all requests. SessionCreationPolicy.STATELESS tells Spring Security never to create an HTTP session, reinforcing that each request authenticates independently.

Custom Login Page

Your login page controller renders the HTML form and must include the CSRF token. Thymeleaf handles this naturally with the Spring Security dialect.

<!DOCTYPE html>
<html xmlns:th="https://www.thymeleaf.org">
  <head>
    <title>Login</title>
    <link rel="stylesheet" th:href="@{/css/login.css}" />
  </head>
  <body>
    <div class="login-container">
      <h2>Sign In</h2>

      <div th:if="${param.error}" class="error-message">
        Invalid username or password.
      </div>
      <div th:if="${param.logout}" class="logout-message">
        You have been logged out.
      </div>

      <form th:action="@{/login}" method="post">
        <input
          type="hidden"
          th:name="${_csrf.parameterName}"
          th:value="${_csrf.token}"
        />
        <div class="form-group">
          <label for="username">Username</label>
          <input type="text" id="username" name="username" autofocus required />
        </div>
        <div class="form-group">
          <label for="password">Password</label>
          <input type="password" id="password" name="password" required />
        </div>
        <button type="submit">Sign In</button>
      </form>
    </div>
  </body>
</html>

The hidden CSRF input field is critical. Without it, Spring Security rejects the POST request with a 403. The form posts to /login, handled internally by UsernamePasswordAuthenticationFilter.

Observability Checklist

Log and monitor security-relevant events to detect attacks and diagnose authentication failures in production.

• Log failed login attempts with username, source IP, and user agent at WARN level
• Log successful authentications at INFO level, capturing session ID for audit trails
• Monitor account lockout state transitions in your application metrics
• Track authentication latency to detect credential stuffing that introduces latency spikes
• Emit events for session creation and destruction to support session hijacking detection
• Capture the HttpServletRequest.remoteAddr for all authentication attempts, aware of proxy headers like X-Forwarded-For
• Send alerts when failed attempts from a single IP exceed a threshold within a time window
• Monitor for users authenticating from impossible geographic locations based on IP geolocation

Spring Security’s ApplicationEvent system publishes events like AuthenticationSuccessEvent and AuthenticationFailureBadCredentialsEvent that you can listen for and forward to your logging infrastructure.

@Component
public class AuthenticationEventListener {

    private static final Logger log = LoggerFactory.getLogger(
        AuthenticationEventListener.class);

    @EventListener
    public void onAuthenticationSuccess(AuthenticationSuccessEvent event) {
        Authentication auth = event.getAuthentication();
        HttpServletRequest request = ((ServletRequestAttributes)
            RequestContextHolder.getRequestAttributes()).getRequest();

        log.info("Authentication success for user: {} from IP: {}",
            auth.getName(),
            request.getRemoteAddr());
    }

    @EventListener
    public void onAuthenticationFailure(
            AuthenticationFailureBadCredentialsEvent event) {
        Authentication auth = event.getAuthentication();
        HttpServletRequest request = ((ServletRequestAttributes)
            RequestContextHolder.getRequestAttributes()).getRequest();

        log.warn("Failed authentication attempt for user: {} from IP: {}",
            auth.getName(),
            request.getRemoteAddr());
    }
}

Security Notes

Hardening your authentication configuration requires attention to details that live in the gap between “works” and “secure.”

Password Encoding

Never store passwords in plain text or using weak hashing algorithms like MD5 or SHA-1. BCryptPasswordEncoder applies bcrypt with a work factor that makes brute-force attacks computationally expensive. Configure it as a bean and inject it wherever password encoding is needed. If you integrate with an existing user store, DelegatingPasswordEncoder routes encoding and matching to the appropriate algorithm based on a stored prefix.

Secure Cookie Flags

Session cookies must include the Secure flag to prevent transmission over plain HTTP, the HttpOnly flag to block JavaScript access, and the SameSite attribute to mitigate CSRF attacks. Spring Boot configures these automatically when server.servlet.session.cookie.secure=true is set. Verify your application.properties or application.yml includes this setting before deploying.

HTTPS Requirement

Both form login and HTTP Basic require HTTPS. For HTTP Basic, credentials travel in the clear without transport encryption, making HTTPS mandatory. For form login, session cookies and form data containing credentials also require encryption in transit. Configure your security filter chain to redirect HTTP to HTTPS or reject non-TLS requests entirely.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .requiresChannel(channel -> channel
                .anyRequest().requiresSecure()
            )
            // ... rest of configuration
        ;
        return http.build();
    }
}

Common Pitfalls

The most frequent mistakes with form login and HTTP Basic are avoidable with some awareness of how the filter chain behaves.

Disabling CSRF globally. Developers sometimes disable CSRF protection to simplify testing, then leave it disabled in production. CSRF protection is essential for form login. Only disable it for stateless APIs consuming credentials in the Authorization header or for endpoints consumed by API clients that handle tokens correctly.

Not invalidating sessions on logout. The default logout behavior in Spring Security invalidates the session and clears the security context. If you customize logout and forget invalidateHttpSession(true), the session persists with the authenticated user still in the security context, giving attackers a window to hijack it.

Hardcoded credentials in configuration. Embedding usernames and passwords directly in application.properties or the security config works for demos but creates credential exposure risk in version control and deployment pipelines. Externalize credentials to a vault or environment variables, and use PasswordEncoder consistently across all authentication entry points.

Ignoring the session creation policy. Form login and HTTP Basic have opposing session requirements. Form login needs sessions. HTTP Basic benefits from stateless operation. Mixing them without explicitly setting SessionCreationPolicy can create unexpected sessions for API clients that never intended to manage session state.

Not handling the authentication entry point correctly. When an unauthenticated request hits a protected resource, Spring Security’s AuthenticationEntryPoint decides what happens. Form login redirects to the login page with a 200 response. HTTP Basic sends a WWW-Authenticate header and returns 401. If your API returns 401 but your frontend expects a redirect to login, you need a custom AuthenticationEntryPoint that handles both formats based on the Accept header.

Credential Replay Risk

HTTP Basic sends credentials with every request, encoded in the Authorization header. If an attacker intercepts the request through a man-in-the-middle attack, they can extract the Base64-encoded username and password and replay them against other endpoints. Unlike form login where credentials travel only during the login POST, HTTP Basic exposes credentials on every request. This makes HTTPS mandatory and increases the attack surface. For high-security applications, consider OAuth2 with short-lived tokens instead, where credentials never travel after initial authentication.

Header Injection in Credentials

Form login submissions and HTTP Basic credentials that contain special characters can introduce header injection vulnerabilities if the server does not sanitize input before using it in HTTP headers. While Spring Security’s filters handle this safely, custom authentication mechanisms that write username or other user data into response headers without validation can enable response splitting attacks. Always validate and encode user input before using it in any HTTP header construction.

Use this checklist when setting up form login or HTTP Basic authentication in a Spring Security application.

• Public paths (/login, /css/**, /health) declared with permitAll()
• All other paths require authentication with authenticated()
• Form login configured with custom or default login page
• Login processing URL posts to /login with CSRF token included
• Logout handler invalidates session and clears cookies
• Session fixation protection enabled (default, do not disable)
• BCryptPasswordEncoder configured for credential storage
• Failed login attempts logged with IP and username
• HTTPS required for all authentication endpoints
• HttpOnly and Secure flags set on session cookie
• SessionCreationPolicy set explicitly for the authentication mechanism
• Account lockout strategy implemented to prevent brute force
• AuthenticationEntryPoint handles both API and browser clients correctly
• Logout redirects to public page after session invalidation

Interview Questions

http
    .authorizeHttpRequests(authz -> authz
        .requestMatchers("/public/**").permitAll()
        .anyRequest().authenticated()
    )
    .formLogin(form -> form
        .loginPage("/login")
        .permitAll()
    )
    .httpBasic(Customizer.withDefaults());

Further Reading

Deepen your understanding of Spring Security authentication with these resources.

• Spring Security Reference Documentation - Official documentation covering all authentication mechanisms
• OAuth 2.0 Resource Server JWT Configuration - Token-based authentication beyond Basic auth
• Spring Security Architecture by Baeldung - Filter chain internals explained
• OWASP Authentication Cheat Sheet - Broader authentication security guidance
• Session Management Cheat Sheet - OWASP session hardening guidelines
• Spring Security with JWT Tokens - Moving beyond session-based auth

Conclusion