Getting HTTP Basic Authentication from HttpServletRequest

1. Introduction

Basic Authentication is the most common security mechanism for HTTP services. Its popularity stems from simplicity and ease of implementation. In this tutorial, we’ll explore how HTTP Basic Authentication works and how to extract credentials, specifically the password, from an incoming HTTP request in a Spring-based application.

2. HTTP Basic Authentication

HTTP Basic Authentication is a simple authentication scheme where the client sends credentials in the HTTP request header. The client sends the request with the credentials included in the Authorization header, and the server then validates them. The header format is:

Authorization: Basic <base64(username:password)>

The username and password are combined into a single string separated by a colon. This string is then encoded using Base64. For example, if the username is admin and the password is secret, the combined string is admin:secret. The Base64 encoded version of this string is YWRtaW46c2VjcmV0. The final HTTP header looks like this:

Authorization: Basic YWRtaW46c2VjcmV0

It’s important to note that Base64 is encoding, not encryption. It is easily reversible, which is why HTTPS is strictly required when using Basic Authentication.

3. Maven Dependency

Let’s start by importing the spring-boot-starter-web dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.3.2</version>
</dependency>

4. Retrieving Credentials from the Authorization Header

In this section, we describe the step-by-step process of retrieving the raw username and password from the incoming HTTP request.

4.1. Manual Extraction from the HTTP Request

The most direct way to get the password is to read the Authorization header directly from the HttpServletRequest and decode it. Let’s create a BasicAuthExtractor class and a utility method to do this:

public class BasicAuthExtractor {

    public static String[] extractCredentials(String authHeader) {
        if (authHeader != null && authHeader.startsWith("Basic ")) {
            String base64Credentials = authHeader.substring("Basic ".length()).trim();
            byte[] credDecoded = Base64.getDecoder().decode(base64Credentials);
            String credentials = new String(credDecoded, StandardCharsets.UTF_8);
            final String[] values = credentials.split(":", 2);

            if (values.length == 2) {
                return values;
            }
        }
        return null;
    }
}

The extractCredentials() method first checks whether the Authorization header exists. It also verifies that the header starts with the “Basic ” prefix. Next, it removes the prefix from the header value. Then, it decodes the remaining Base64-encoded string using Base64.getDecoder(). After decoding, the bytes are converted into a UTF-8 string.

The resulting string should follow the username:password format. Finally, the method splits the string on the first colon. It returns a two-element array containing the username and password. If the header is invalid or incorrectly formatted, the method returns null.

We can easily use the extractCredentials() method inside a RestController:

@GetMapping("/extract")
public ResponseEntity<String> extract(@RequestHeader("Authorization") String authHeader) {
    String[] credentials = BasicAuthExtractor.extractCredentials(authHeader);

    if (credentials != null) {
        String username = credentials[0];
        String password = credentials[1];
        return ResponseEntity.ok("Extracted Username: " + username +
          " Extracted Password: " + password);
    }

    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}

We use the @RequestHeader annotation for getting the Authorization header value from the incoming request.

4.2. Custom Servlet Filter

Another way is to create a custom Filter that reads the header, extracts the password, and stores it in a request attribute for later use. Let’s create an AuthFilter class to do this:

@Component
public class AuthFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
        FilterChain filterChain) throws ServletException, IOException {

        String authHeader = request.getHeader("Authorization");
        String[] credentials = BasicAuthExtractor.extractCredentials(authHeader);

        if (credentials != null) {
            request.setAttribute("rawPassword", credentials[1]);
        }

        filterChain.doFilter(request, response);
    }
}

This filter intercepts every incoming HTTP request and reads the Authorization header. Then, it extracts the password using the extractCredentials() method and stores it as a request attribute before continuing the filter chain. Later, in our service or controller, we can retrieve it safely:

String rawPassword = (String) request.getAttribute("rawPassword");

5. Testing the BasicAuthExtractor

Let’s start by testing the core extraction logic. First, we need to ensure it correctly handles a valid Basic Authentication header and returns the expected credentials array:

@Test
void givenValidHeader_whenExtract_thenReturnCredentialsArray() {
    // Given
    String header = encodeCredentials("admin", "secret");

    // When
    String[] credentials = BasicAuthExtractor.extractCredentials(header);

    // Then
    assertThat(credentials).isNotNull();
    assertThat(credentials).hasSize(2);
    assertThat(credentials[0]).isEqualTo("admin");
    assertThat(credentials[1]).isEqualTo("secret");
}

To keep our tests clean and readable, we utilize a helper method that handles the Base64 encoding and header formatting for us:

private String encodeCredentials(String username, String password) {
    String credentials = username + ":" + password;
    return "Basic " + Base64.getEncoder().encodeToString(credentials.getBytes());
}

Additionally, we need to verify that the method safely returns null for invalid headers, such as those missing the Basic prefix or using a different authentication scheme:

@Test
void givenMissingBasicPrefix_whenExtract_thenReturnNull() {
    // Given
    String header = "Bearer some-token";

    // When
    String[] credentials = BasicAuthExtractor.extractCredentials(header);

    // Then
    assertThat(credentials).isNull();
}

6. Conclusion

In this article, we learned how HTTP Basic Authentication encodes credentials and how to decode them manually using Java’s Base64 utility. We also explored how to capture the raw password using a custom filter. While extracting passwords is sometimes necessary for legacy integrations, it should be avoided whenever possible due to the inherent security risks. As always, the source code is available over on GitHub.