Spring Security Part 4: Basic Authentication (Stateless)

Form login (part 3) keeps a session on the server. The next methods are stateless: the server remembers nothing between requests, so any server instance can handle any request. The simplest is Basic authentication.

Basic authentication

Basic authentication is stateless: the server keeps no authentication state, no session. So the client sends the username and password with every request, in the Authorization header:

Authorization: Basic <base64(username:password)>

For user / pass:

Authorization: Basic dXNlcjpwYXNz

Base64 is an encoding, not encryption. Anyone who sees the header can decode dXNlcjpwYXNz back to user:pass instantly. Over plain HTTP the credentials are exposed, so use basic authentication only over HTTPS.

A user for testing

Any of the ways from part 2 works; for testing:

spring.security.user.name=user
spring.security.user.password=pass
spring.security.user.roles=ADMIN,USER

Reading the header

BasicAuthenticationFilter reads and decodes the header:

// BasicAuthenticationConverter.convert, simplified
String header = request.getHeader(HttpHeaders.AUTHORIZATION);   // read the Authorization header
if (header == null) {
    return null;                                                 // no basic authentication here
}
header = header.trim();
if (!StringUtils.startsWithIgnoreCase(header, "Basic")) {
    return null;
}
if (header.equalsIgnoreCase("Basic")) {
    throw new BadCredentialsException("Empty basic authentication token");
}
byte[] base64Token = header.substring(6).getBytes(StandardCharsets.UTF_8);
byte[] decoded = decode(base64Token);                            // decode username:password
String token = new String(decoded, getCredentialsCharset(request));
int delim = token.indexOf(":");
// username = before ':', password = after it

Why a header, and not the request body?

1. Standard. RFC 7617 defines this format, so every API and client understands it. If some APIs wanted credentials in the body and others in headers, working with many APIs and clients would be painful.
2. Less exposure in logs. Web servers and tools sometimes log request bodies (and query parameters) for debugging or analytics, sometimes into third-party logging systems. The Authorization header is widely treated as sensitive and is normally kept out of such logs. (Not guaranteed: check what your own logging captures.)
3. Works for every method. GET requests have no body; a header works the same for GET, POST, PUT and DELETE.

The flow

It is form login's flow squeezed into one request: authentication and authorization happen together, and no session is created.

BasicAuthenticationFilter decodes the header, builds a UsernamePasswordAuthenticationToken and passes it to the ProviderManager; DaoAuthenticationProvider loads the user and checks the password, exactly as in form login. The authenticated object goes into the SecurityContextHolder for this request only. Then the AuthorizationFilter checks the roles, as before.

Configuration

Only the security starter is needed; there is no session, so no spring-session-jdbc. Since form login is the default, override the SecurityFilterChain and choose basic authentication:

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/users").hasAnyRole("USER")   // authorization
                .anyRequest().authenticated())
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))   // no session
            .csrf(csrf -> csrf.disable())                           // no session cookie, so no CSRF risk
            .httpBasic(Customizer.withDefaults());                  // basic authentication
        return http.build();
    }
}

• STATELESS: no session is ever created; responses set no session cookie.
• CSRF disabled: CSRF abuses credentials the browser sends automatically, such as a session cookie. Here the client adds the header itself on every request, so there is nothing to forge.

Results:

Request	Response
No Authorization header	401, with WWW-Authenticate: Basic realm="Realm"
Wrong password	401
Correct credentials	200
Correct credentials, missing role	403

The WWW-Authenticate header is what makes a browser show its built-in username/password popup.

Drawbacks

1. Credentials travel with every request. Without HTTPS they can be intercepted and decoded.
2. No way to revoke access short of changing the password: there is no session or token to invalidate.
3. Poor fit for large applications:
   • every request is larger, carrying the header
   • every request repeats the work: decoding, hashing the incoming password and comparing
   • every request loads the user from the database, adding latency

These drawbacks lead to token-based methods such as JWT (next parts).

Next: Part 5 explains JWT, a signed token that replaces sending the password with every request.

Check yourself

1. Why is basic authentication stateless, and what must the client send with each request?
2. Is Basic dXNlcjpwYXNz secure? What does it contain?
3. Give three reasons the credentials go in a header rather than the body.
4. Which filter handles basic authentication, and what does it build?
5. What is different about the flow compared with form login?
6. Why is the session policy STATELESS, and why can CSRF be disabled?
7. What does the server return when the header is missing, and why does a browser then show a login popup?
8. Give three drawbacks of basic authentication.

Answers

1. The server keeps no session; the client sends Authorization: Basic <base64(username:password)> every time.
2. No: it is Base64 for user:pass, which anyone can decode. Use HTTPS.
3. It is the HTTP standard (RFC 7617); bodies are more often logged than the Authorization header; GET has no body.
4. BasicAuthenticationFilter; a UsernamePasswordAuthenticationToken.
5. Authentication and authorization happen in the same request, and no session is created; the context lives only for that request.
6. The method keeps no state, so no session is needed; CSRF abuses automatically sent cookies, and there are none here.
7. 401 with WWW-Authenticate: Basic realm="Realm", which tells the browser to ask for credentials.
8. Credentials in every request (dangerous without HTTPS); no revocation except changing the password; overhead per request (bigger requests, decoding, hashing, database lookup).