Kora HTTP Server Auth

Kora HTTP Server Auth

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Kora has no @Secured-style annotation. Authentication is either contract-driven — the OpenAPI generator emits the whole interceptor and you supply one HttpServerPrincipalExtractor per security scheme — or manual, a hand-written HttpServerInterceptor. Both end the same way: the authenticated Principal is published with Principal.with(...) and read inside the handler with Principal.current().

What changed from Kora 1.x — read this before porting auth code

Quick start — OpenAPI security scheme

1. Declare the scheme in the contract

security:
  - apiKeyAuth: []            # applies to every operation

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

2. What the generator emits

The kora generator writes an ApiSecurity interface into your api package. It is annotated @Module, so the Kora processor picks it up automatically — do not add it to your @KoraApp interface list. For the contract above it contains:

• a marker class ApiSecurity.ApiKeyAuth — the tag,
• an interceptor ApiSecurity.ApiKeyAuthHttpServerInterceptor that reads the header, calls your extractor, publishes the principal and throws 401 when nothing authenticated,
• a @DefaultComponent factory whose only parameter is the extractor you must provide:

@Tag(ApiKeyAuth.class)
@DefaultComponent
default ApiKeyAuthHttpServerInterceptor ApiKeyAuthHttpServerInterceptor(
    @Tag(ApiKeyAuth.class) HttpServerPrincipalExtractor<String, Principal> ApiKeyAuth_) { … }

That parameter type is the exact signature your extractor must have. See references/openapi-security-reference.md for the full generated shape, the tag-naming rule, and the AND/OR/anonymous variants.

3. Define a Principal

import io.koraframework.common.Principal;

public record DataApiPrincipal(String clientId) implements Principal {}

4. Supply the extractor

import io.koraframework.common.Principal;
import io.koraframework.common.annotation.Tag;
import io.koraframework.http.server.common.auth.HttpServerPrincipalExtractor;

@Tag(ApiSecurity.ApiKeyAuth.class)
default HttpServerPrincipalExtractor<String, Principal> apiKeyHttpServerPrincipalExtractor(
        DataApiAuthConfig config) {
    return (request, value) -> {
        if (value == null || !config.value().equals(value)) {
            return null;               // → generated interceptor throws 401 Unauthorized
        }
        return new DataApiPrincipal("data-api-client");
    };
}

Kotlin — the SAM parameter is nullable, and so is the result:

@Tag(ApiSecurity.ApiKeyAuth::class)
fun apiKeyHttpServerPrincipalExtractor(
    config: DataApiAuthConfig
): HttpServerPrincipalExtractor<String, Principal> =
    HttpServerPrincipalExtractor { _, value ->
        if (value == null || config.value() != value) null
        else DataApiPrincipal("data-api-client")
    }

Externalize the secret — never inline it:

@ConfigSource("auth.apiKey")
public interface DataApiAuthConfig { String value(); }

auth { apiKey { value = ${API_KEY} } }

5. Read the principal in the handler

import io.koraframework.common.Principal;

var principal = (DataApiPrincipal) Principal.current();   // null when the route is anonymous

Principal.current() reads a ScopedValue bound by the interceptor for the duration of the request. It is @Nullable, and it is not visible on threads you start yourself.

Rejecting a request

extract returning null is the only rejection signal the generated interceptor understands.

Do not throw SecurityException. The string SecurityException appears in no Kora 2.0 source file. An uncaught one reaches the Undertow handler, which turns any non-HttpServerResponse throwable into 500 with the exception message as the plaintext body — leaking internals while looking like a server bug.

Global interceptors

import io.koraframework.common.annotation.Component;
import io.koraframework.common.annotation.Tag;
import io.koraframework.http.server.common.HttpServer;
import io.koraframework.http.server.common.interceptor.HttpServerInterceptor;

@Tag(HttpServer.class)      // NOT HttpServerModule.class
@Component
public final class AuthErrorInterceptor implements HttpServerInterceptor {

    @Override
    public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
        try {
            return chain.process(request);
        } catch (HttpServerResponseException e) {
            return jsonError(e.code(), e.getMessage());
        }
    }
    …
}

HttpServerModule collects them as @Tag(HttpServer.class) All<HttpServerInterceptor>, so:

• many global interceptors are allowed (1.x's "only one" no longer applies);
• they are sorted by simple class name, and the chain is wound so the alphabetically last name runs outermost;
• they wrap everything, including the generated security interceptor — this is the only place that can reshape the generated 401.

The OpenAPI interceptors generator option puts your interceptor inside the security interceptor, so it cannot see the 401 the latter throws. Use @Tag(HttpServer.class) for that.

Manual auth (no OpenAPI contract)

Mirror what the generator does: validate, then publish the principal.

@Component
public final class ApiKeyInterceptor implements HttpServerInterceptor {

    private final AuthConfig config;

    public ApiKeyInterceptor(AuthConfig config) { this.config = config; }

    @Override
    public HttpServerResponse intercept(HttpServerRequest request, InterceptChain chain) throws Exception {
        var key = request.headers().getFirst("x-api-key");
        if (key == null || !this.config.apiKey().equals(key)) {
            throw HttpServerResponseException.of(401, "Unauthorized");
        }
        return Principal.with(new ApiKeyPrincipal(key), () -> chain.process(request));
    }
}

Scope it with @InterceptWith(ApiKeyInterceptor.class) on the @HttpController class or the @HttpRoute method, or make it global with @Tag(HttpServer.class). Full patterns, including HttpServerRequestMapper + @Mapping: references/manual-auth-reference.md.

Pitfalls

What's in this skill

Related skills

• kora-http-server — controllers, routes, interceptors, error handling
• kora-openapi-generator-server — generator wiring that produces ApiSecurity
• kora-http-client-auth — outbound credentials (a different ApiSecurity shape)
• kora-config-hocon — @ConfigSource for secrets
• kora-json — JSON error bodies and JWT claim DTOs
• kora-testing-junit-java · kora-testing-junit-kotlin — @KoraAppTest coverage for auth