API Key Authentication Filters

Welcome back! In the previous lesson, you learned how to generate secure API keys, store them safely using hashing, and create an endpoint for users to request new keys. Now that you know how to create and manage API keys, it is time to learn how to use them to authenticate requests to your API.

In this lesson, you will integrate API key authentication into your application using Spring Boot interceptors and custom authentication logic. You will see how to validate API keys, check their format, compare them securely with stored hashes, and handle expired keys. You will also learn how to combine API key authentication with JWT authentication, giving your API the flexibility to support both methods. By the end of this lesson, you will be able to implement robust API key authentication and understand how it fits into a secure API architecture.

Before diving into the code, let's quickly review how authentication works in Spring Boot and why custom authentication logic is important. In Spring Boot, you can implement authentication using various approaches, including filters, interceptors, or custom components. For API key authentication, we typically create a method that can be called from controllers to verify credentials before any sensitive logic runs.

API key authentication logic is responsible for checking if a request includes a valid API key and, if so, allowing the request to proceed. If the key is missing or invalid, the method throws an exception that stops the request and returns an error. This approach helps protect your API from unauthorized access and ensures that only users with valid keys can use your service.

When a client sends a request to your API, they include their API key in the X-API-Key header. Before you check if the key is valid, you should first make sure it is in the correct format. In our example, every API key starts with the prefix pb_ and is followed by 64 hexadecimal characters, making the total length 67 characters.

Here is the code that checks the format:

private boolean isValidApiKeyFormat(String key) {
    if (!key.startsWith("pb_") || key.length() != 67) {
        return false;
    }
    // Verify that characters after pb_ are hexadecimal
    String keyPart = key.substring(3);
    return keyPart.matches("[0-9a-f]{64}");
}

This validation serves two purposes. First, it checks the prefix and length to quickly reject obviously malformed keys. Second, it verifies that the remaining 64 characters are valid hexadecimal digits (0-9 and a-f). This extra check ensures that only properly formatted keys proceed to the more expensive database lookup and hash comparison steps.

If the key does not match this format, the authentication function immediately throws an exception. This helps prevent unnecessary database lookups and can stop some simple attacks. Once the format is confirmed, the function removes the pb_ prefix to get the raw key, which is what was originally generated and given to the user. This raw key is what you will compare against the stored hashes.

For example, if the incoming header is:

X-API-Key: pb_4f3c2e1a1234567890abcdef1234567890abcdef1234567890abcdef12345678

The authentication function will extract 4f3c2e1a1234567890abcdef1234567890abcdef1234567890abcdef12345678 for verification.

Now that you have the raw key, you need to check if it matches any of the active API keys stored in your database. Remember from the previous lesson that you never store the raw key itself — only a hash of the key, using BCrypt.

Note on Implementation Approach: In this lesson, we'll preview an optimized database design using an indexed lookupHash field for O(1) performance. However, the practices in this unit will start with a simpler linear scan approach for educational purposes, allowing you to understand the fundamentals before implementing optimizations. You'll implement the optimized lookupHash approach in later practices once you're comfortable with the core authentication flow.

To efficiently find the correct API key to verify in a production system, you would use a lookupHash field. A database index is a special data structure that allows the database to quickly locate records without scanning every row. Think of it like an index in a book — instead of reading every page to find a topic, you look it up in the index and jump directly to the right page. Database indexes work similarly by maintaining a sorted reference to your data. When you query by an indexed field, the database can use efficient search algorithms (like binary search) to find records in O(log n) or even O(1) time, instead of scanning all rows which would take O(n) time. This becomes critical as your database grows — with millions of API keys, an indexed lookup might take milliseconds while a full table scan could take seconds.

Here is how you would define the indexed field in your entity:

@Entity
@Table(
    name = "api_keys",
    indexes = { @Index(name = "idx_lookup_hash", columnList = "lookupHash") }
)
public class ApiKey {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;
    
    @Column(nullable = false, unique = true)
    private String lookupHash;
    
    @Column(nullable = false)
    private String keyHash;
    
    @Column(nullable = false)
    private Boolean isActive = true;
    
    @Column(nullable = false)
    private LocalDateTime expiresAt;
    
    // Getters and setters...
}

The @Table annotation with indexes parameter creates a database index that allows fast lookups without scanning all rows. Here is how the authentication function would use the lookup hash in an optimized implementation:

import java.security.MessageDigest;
import java.nio.charset.StandardCharsets;
import org.springframework.security.crypto.password.PasswordEncoder;

// Create lookup hash for O(1) database query
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hashBytes = digest.digest(keyToCheck.getBytes(StandardCharsets.UTF_8));
StringBuilder hexString = new StringBuilder();
for (byte b : hashBytes) {
    String hex = Integer.toHexString(0xff & b);
    if (hex.length() == 1) hexString.append('0');
    hexString.append(hex);
}
String lookupHash = hexString.toString();

Optional<ApiKey> apiKeyOpt = apiKeyRepository.findByLookupHashAndIsActiveTrue(lookupHash);

if (apiKeyOpt.isPresent() && passwordEncoder.matches(keyToCheck, apiKeyOpt.get().getKeyHash())) {
    matchedApiKey = apiKeyOpt.get();
    authenticationResult = true;
}

This two-step approach uses the lookupHash for fast O(1) database lookup, then verifies the key securely with BCrypt. Understanding this optimized pattern will help you design scalable authentication systems, even though you'll start with a simpler approach in the practices.

If no match is found, the function throws a custom exception with a 401 status code. This means the key is either invalid or does not belong to any active user. If a match is found, the request can continue. This process ensures that even if someone gains access to your database, they cannot use the hashes to authenticate because BCrypt hashes are one-way and cannot be reversed.

If the key is missing or invalid, the response might look like this:

{
  "detail": "Invalid API key"
}

Even if an API key is valid, it might be expired. Each key has an expiresAt field, and the authentication function checks if the current date is past this expiration. If the key is expired, the request is rejected with an error message and the expiration date.

For example, if a key is expired, the response could be:

{
  "detail": "API key expired",
  "message": "2024-06-10T12:34:56"
}

If the key is valid and not expired, the function attaches the user and API key information to the request. In Spring Boot, you can store this information in request attributes. For example, after authentication, you can store the user object:

request.setAttribute("user", user);
request.setAttribute("apiKeyId", apiKey.getId());

This allows downstream controller methods to know which user is making the request and which key was used. This is useful for logging, rate limiting, or applying user-specific logic.

In many real-world applications, you may want to support both API key and JWT authentication. For example, your web frontend might use JWTs, while third-party integrations use API keys. The authentication function can be designed to check for an API key first, and if none is found, fall back to checking for a JWT in the Authorization header.

To implement this flexible authentication, you need to create a reusable service that can be injected into your controllers or other components. In Spring Boot, the @Component annotation marks a class as a Spring-managed bean, which means Spring will automatically create an instance of it and make it available for dependency injection throughout your application. This allows you to use the authentication service anywhere you need it without manually creating instances.

Here is how the flexible authentication function works:

import com.auth0.jwt.interfaces.DecodedJWT;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Component;

@Component
public class FlexibleAuthService {
    private final ApiKeyRepository apiKeyRepository;
    private final UserRepository userRepository;
    private final JwtUtil jwtUtil;
    private final PasswordEncoder passwordEncoder;
    
    public FlexibleAuthService(ApiKeyRepository apiKeyRepository, 
                               UserRepository userRepository,
                               JwtUtil jwtUtil, 
                               PasswordEncoder passwordEncoder) {
        this.apiKeyRepository = apiKeyRepository;
        this.userRepository = userRepository;
        this.jwtUtil = jwtUtil;
        this.passwordEncoder = passwordEncoder;
    }
    
    public User authenticate(HttpServletRequest request) {
        String apiKey = request.getHeader("X-API-Key");
        String authHeader = request.getHeader("Authorization");
        
        // Try API key first if present
        if (apiKey != null && !apiKey.isBlank()) {
            return authenticateApiKey(request, apiKey);
        }
        
        // Fallback to JWT authentication
        if (authHeader != null && authHeader.startsWith("Bearer ")) {
            try {
                String token = authHeader.substring(7);
                DecodedJWT decoded = jwtUtil.verify(token);
                Integer userId = decoded.getClaim("userId").asInt();
                
                User user = userRepository.findById(userId)
                    .orElseThrow(() -> new AuthException(404, "User not found"));
                
                request.setAttribute("user", user);
                request.setAttribute("authMethod", "jwt");
                return user;
                
            } catch (Exception e) {
                throw new AuthException(401, "Invalid JWT token");
            }
        } else {
            throw new AuthException(
                401,
                "Authentication required",
                "Provide either Bearer token or X-API-Key header"
            );
        }
    }
    
    private User authenticateApiKey(HttpServletRequest request, String apiKey) {
        // Implementation from previous sections
        // Validates format, checks hash, handles expiration
        // Returns user and sets request attributes
    }
}

This approach gives your API flexibility and makes it easier to support different types of clients. It also allows you to gradually migrate from one authentication method to another or to offer both for different use cases.

In this lesson, you learned how to integrate API key authentication into your Spring Boot application using custom authentication logic. You saw how to validate the format of API keys, extract and verify them securely using BCrypt, handle expired keys, and attach user information to requests. You also learned how to combine API key and JWT authentication for a flexible and secure API.

You are now ready to practice these concepts in the hands-on exercises that follow. Remember, on CodeSignal, all the necessary libraries are pre-installed, so you can focus on writing and testing your code. Keep up the great work — these skills are essential for building secure APIs that can support a variety of clients and use cases.