kora-http-server-auth

Kora HTTP Server Auth

Kora sub-skill — obey the kora-v1 meta rules on every task: R0 ensure .kora-agent/ docs+examples are cloned · R1 read this sub-skill before writing code · R2 Kora APIs only — no Spring/Micronaut/Quarkus, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Authenticate and authorize Kora HTTP server endpoints. Kora has no @Secured-style annotation and no thread-local "current user". Authentication is implemented in one of two ways:

• OpenAPI-driven (preferred when you generate the server from a contract): implement HttpServerPrincipalExtractor<P> and bind it with @Tag(ApiSecurity.<Scheme>.class). The generated controller invokes the matching extractor before your delegate runs.
• Manual (no OpenAPI contract): an HttpServerInterceptor validates credentials and short-circuits, and/or an HttpServerRequestMapper<P> turns the request into a typed argument injected via @Mapping.

All Kora artifacts inherit the version from the kora-parent BOM (1.2.19 in .kora-agent/kora-examples). Never pin individual ru.tinkoff.kora:* versions.

---

Quick Start (OpenAPI security)

1. Dependencies

dependencies {
    koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19")
    annotationProcessor "ru.tinkoff.kora:annotation-processors" // mandatory: generates the graph + controllers

    implementation "ru.tinkoff.kora:http-server-undertow"
    implementation "ru.tinkoff.kora:json-module"
    implementation "ru.tinkoff.kora:config-hocon"
    implementation "ru.tinkoff.kora:logging-logback"
}

The OpenAPI kora generator produces the ApiSecurity class (one nested marker per securityScheme) from the contract's components.securitySchemes. See kora-openapi-generator-server for the generator wiring.

2. Declare the security scheme in the contract

security:
    -   apiKeyAuth: [ ]            # apply globally to every operation

components:
    securitySchemes:
        apiKeyAuth:
            type: apiKey
            in: header
            name: Authorization