Layer 4 — API Key Authentication: Securing Machine-to-Machine Requests

@Component
@Order(3)  // after TenantResolver (1) and JwtFilter (2)
public class ApiKeyFilter extends OncePerRequestFilter {

    private final ApiKeyService apiKeyService;

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

        // CRITICAL: If a valid session/JWT already authenticated this request, skip.
        // This is the session passthrough fix — see below.
        Authentication existingAuth = SecurityContextHolder.getContext().getAuthentication();
        if (existingAuth != null && existingAuth.isAuthenticated()) {
            chain.doFilter(request, response);
            return;
        }

        String apiKey = request.getHeader("X-API-KEY");

        if (apiKey == null || apiKey.isBlank()) {
            // No API key provided — pass through. Spring Security decides if auth is required.
            chain.doFilter(request, response);
            return;
        }

        // Validate the key
        ApiKeyPrincipal principal = apiKeyService.validate(apiKey, TenantContext.getCurrentTenant());

        if (principal == null) {
            response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Invalid API key");
            return;
        }

        // Set authentication in SecurityContext
        ApiKeyAuthenticationToken auth = new ApiKeyAuthenticationToken(
            principal,
            principal.getAuthorities()
        );
        SecurityContextHolder.getContext().setAuthentication(auth);

        chain.doFilter(request, response);
    }
}

// This check must be FIRST in the filter, before reading X-API-KEY
Authentication existingAuth = SecurityContextHolder.getContext().getAuthentication();
if (existingAuth != null && existingAuth.isAuthenticated()) {
    chain.doFilter(request, response);
    return;
}

// On key creation — return the plaintext key to the caller ONCE
public ApiKeyCreationResult createKey(String tenantDomain, String label) {
    String rawKey = generateSecureKey();       // 32 bytes of SecureRandom, base64url-encoded
    String hashedKey = hash(rawKey);           // SHA-256 or bcrypt

    ApiKey entity = new ApiKey();
    entity.setDomain(tenantDomain);
    entity.setLabel(label);
    entity.setKeyHash(hashedKey);
    entity.setCreatedAt(Instant.now());
    entity.setLastUsedAt(null);
    repository.save(entity);

    // Return plaintext key to caller — this is the ONLY time it's available
    return new ApiKeyCreationResult(entity.getId(), rawKey);
}

// On validation — hash the incoming key and compare
public ApiKeyPrincipal validate(String rawKey, String tenantDomain) {
    String hash = hash(rawKey);
    return repository.findByKeyHashAndDomain(hash, tenantDomain)
                     .map(key -> {
                         key.setLastUsedAt(Instant.now());  // audit trail
                         repository.save(key);
                         return new ApiKeyPrincipal(key);
                     })
                     .orElse(null);
}

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
            // Public endpoints — no auth required
            .requestMatchers("/api/appoint/day/**", "/api/appoint/request").permitAll()

            // API-key-accessible admin endpoints — explicitly listed
            .requestMatchers("/api/admin/report/weekly").hasAuthority("ROLE_API_CLIENT")
            .requestMatchers("/api/admin/import/csv").hasAuthority("ROLE_API_CLIENT")

            // Everything else requires JWT-based auth
            .anyRequest().hasAnyRole("USER", "ADMIN")
        );
        return http.build();
    }
}

class ApiKeyFilterTest {

    @Test
    void validApiKey_authenticatesRequest() throws Exception {
        String key = "myapp_test_validkeyvalue";
        when(apiKeyService.validate(key, "tenant.example.com"))
            .thenReturn(new ApiKeyPrincipal("tenant.example.com", List.of("ROLE_API_CLIENT")));

        request.addHeader("X-API-KEY", key);
        TenantContext.setCurrentTenant("tenant.example.com");

        filter.doFilterInternal(request, response, chain);

        assertThat(SecurityContextHolder.getContext().getAuthentication()).isNotNull();
        assertThat(response.getStatus()).isNotEqualTo(401);
    }

    @Test
    void invalidApiKey_returns401() throws Exception {
        when(apiKeyService.validate(any(), any())).thenReturn(null);

        request.addHeader("X-API-KEY", "myapp_test_badkey");

        filter.doFilterInternal(request, response, chain);

        assertThat(response.getStatus()).isEqualTo(401);
    }

    @Test
    void noApiKey_passesThroughToNextFilter() throws Exception {
        // No X-API-KEY header — chain should continue
        filter.doFilterInternal(request, response, chain);

        verify(chain).doFilter(request, response);
        assertThat(SecurityContextHolder.getContext().getAuthentication()).isNull();
    }

    // THE CRITICAL SESSION PASSTHROUGH TEST
    @Test
    void existingValidSession_withInvalidApiKey_doesNotReturn401() throws Exception {
        // Simulate a valid session already in the SecurityContext (set by JWT filter)
        Authentication existingAuth = new UsernamePasswordAuthenticationToken(
            "alice", null, AuthorityUtils.createAuthorityList("ROLE_USER")
        );
        SecurityContextHolder.getContext().setAuthentication(existingAuth);

        // Add an invalid API key header (simulates browser extension / bad client config)
        request.addHeader("X-API-KEY", "myapp_test_invalidkey");
        when(apiKeyService.validate(any(), any())).thenReturn(null);

        filter.doFilterInternal(request, response, chain);

        // MUST pass through — the existing session should NOT be invalidated
        verify(chain).doFilter(request, response);
        assertThat(response.getStatus()).isNotEqualTo(401);
    }

    @Test
    void validApiKey_wrongTenant_returns401() throws Exception {
        // Key is valid for tenant-a, but request is for tenant-b
        when(apiKeyService.validate(any(), eq("tenant-b.example.com"))).thenReturn(null);

        request.addHeader("X-API-KEY", "myapp_test_tenantakey");
        TenantContext.setCurrentTenant("tenant-b.example.com");

        filter.doFilterInternal(request, response, chain);

        assertThat(response.getStatus()).isEqualTo(401);
    }
}