Kora HTTP Client Auth

Kora HTTP Client 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.

Everything in this skill is verified against the framework source at tag 2.0.0.RC1 and the migrated examples on migration/2.0 — see Source of truth.

1. The three signatures that decide everything

public interface HttpClientTokenProvider {
    @Nullable String getToken(HttpClientRequest request);      // synchronous, one argument
}

public interface HttpClientInterceptor {
    HttpClientResponse processRequest(InterceptChain chain, HttpClientRequest request) throws Exception;

    interface InterceptChain {
        HttpClientResponse process(HttpClientRequest request) throws Exception;
    }
}

Three consequences, and every 1.x auth flow has to be redesigned around them:

1. No Context. Context was removed from the whole framework — there is no first parameter to thread and nothing to migrate it to. Telemetry propagation is handled by TelemetryInterceptor through ScopedValue, not by anything you write.
2. No CompletionStage. getToken returns a String, processRequest returns a HttpClientResponse. A token fetch blocks, which is correct: Kora 2.0 contracts run on virtual threads. In Kotlin do not reach for suspend, runBlocking or Dispatchers.IO — suspend is not a Kora contract and the dispatcher wrapper is pure overhead.
3. The chain comes first. processRequest(chain, request) — a mechanical port of the 1.x (ctx, chain, request) order that only deletes ctx puts the arguments in the right places by luck; check them.

getToken may return null, and both BasicAuthHttpClientInterceptor and BearerAuthHttpClientInterceptor then forward the request with no credential header at all. That is the intended way to say "this scheme does not apply here" — and the reason a misconfigured secret shows up as an upstream 401 rather than a startup failure.

2. Quick start — API key on every request

build.gradle (koraVersion=2.0.0.RC1 in gradle.properties, resolved from plain mavenCentral()):

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")

    annotationProcessor "io.koraframework:annotation-processors"

    implementation "io.koraframework:config-hocon"
    implementation "io.koraframework:http-client-common"
    implementation "io.koraframework:http-client-ok"
    implementation "io.koraframework:json-common"
    implementation "io.koraframework:logging-logback"
}

@ConfigSource("auth.serviceA")
public interface ServiceAAuthConfig {

    String apiKey();
}

@Module
public interface ServiceAAuthModule {

    default ApiKeyHttpClientInterceptor serviceAApiKeyInterceptor(ServiceAAuthConfig config) {
        return new ApiKeyHttpClientInterceptor(
                ApiKeyHttpClientInterceptor.ApiKeyLocation.HEADER, "X-API-KEY", config.apiKey());
    }
}

@InterceptWith(ApiKeyHttpClientInterceptor.class)
@HttpClient("httpClient.serviceA")
public interface ServiceAClient {

    @HttpRoute(method = HttpMethod.GET, path = "/resource")
    @Json
    Resource getResource();
}

@KoraApp
public interface Application extends
        HoconConfigModule,
        JsonModule,
        LogbackModule,
        OkHttpClientModule,
        ServiceAAuthModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

auth.serviceA.apiKey = ${SERVICE_A_API_KEY}

httpClient.serviceA {
  url = "https://api.service-a.example"
  telemetry.logging.maskHeaders = ["authorization", "set-cookie", "cookie", "x-api-key"]
}

ServiceAAuthModule is hand-written, so it must be listed in @KoraApp extends. ServiceAAuthConfig and ServiceAClient must not be — the config and HTTP-client processors register those through compiler extensions, exactly as in the upstream examples.

Kotlin is the same wiring with KSP instead of the annotation processor:

@ConfigSource("auth.serviceA")
interface ServiceAAuthConfig {
    fun apiKey(): String
}

@Module
interface ServiceAAuthModule {
    fun serviceAApiKeyInterceptor(config: ServiceAAuthConfig) = ApiKeyHttpClientInterceptor(
        ApiKeyHttpClientInterceptor.ApiKeyLocation.HEADER, "X-API-KEY", config.apiKey()
    )
}

3. Use this skill / do not

Use it when you attach Authorization: Basic|Bearer or an API key to outbound requests, implement HttpClientTokenProvider for OAuth2 client credentials or a refreshable JWT, write a custom HttpClientInterceptor for a non-standard scheme, retry a request after a 401, or port a 1.x Context/CompletionStage token flow.

Do not use it when you:

Kora ships the building blocks for service-to-service auth only. There is no authorization-code / user-consent OAuth2 flow anywhere in http-client-common; assemble it yourself or use a library.

4. Attaching an interceptor

@InterceptWith(SomeInterceptor.class) on the interface applies to every route; on a method it applies to that route in addition to the class-level ones. Class-level interceptors run first. The annotation is @Repeatable, and @InterceptWith(value = X.class, tag = Y.class) selects a tagged component. There is no interceptors = {...} attribute on @HttpClient.

The named class must be a graph component, and must have exactly one provider. The generated client takes each interceptor as a constructor parameter and nothing in the framework constructs one for you:

• Your own interceptor class → put @Component on it. This holds whether or not it has constructor dependencies — the migrated examples annotate dependency-free interceptors too. (The "no dependencies ⇒ no @Component" rule applies to mappers, whose generated modules do build them; it does not apply to interceptors.)
• A framework interceptor (BasicAuthHttpClientInterceptor, ApiKeyHttpClientInterceptor, BearerAuthHttpClientInterceptor) → you cannot annotate it, so supply it from a @Module factory method.
• Never both. @Component on a class that a @Module also provides gives Multiple components match dependency: with a Candidates: list.
• Neither gives No component found for dependency: naming the interceptor type.

5. Choosing the built-in

ApiKeyHttpClientInterceptor calls Objects.requireNonNull on the secret, so a null key fails during graph init. The Basic and Bearer interceptors do not — see §1.

Full walk-through with config: references/http-client-auth-reference.md.

6. Dynamic tokens

Implement HttpClientTokenProvider, cache the token, and refresh ahead of expiry:

@Component
public final class CachingTokenProvider implements HttpClientTokenProvider {

    private final TokenCache cache;
    private final AuthClient authClient;

    public CachingTokenProvider(TokenCache cache, AuthClient authClient) {
        this.cache = cache;
        this.authClient = authClient;
    }

    @Override
    public String getToken(HttpClientRequest request) {
        return cache.getOrRefresh(() -> {
            var response = authClient.requestToken();
            return TokenCache.Token.of(response.accessToken(), Duration.ofSeconds(response.expiresIn()));
        });
    }
}

The fetch blocks the calling virtual thread, which is what you want; the only thing that needs care is that concurrent callers must not all fetch. TokenCache does a lock-free read, then a ReentrantLock with a re-check — see references/token-cache-reference.md.

• Refresh flow, refresh margin, and retrying a 401: references/jwt-token-provider-reference.md
• Whole OAuth2 client-credentials setup: references/oauth2-client-credentials-reference.md

7. Token providers for an OpenAPI-generated client

The kora OpenAPI generator emits an ApiSecurity @Module next to the generated API. For http basic and apiKey schemes it supplies the token provider itself from generated config; for bearer and oauth2 schemes it supplies nothing and the graph asks you for

@Tag(ApiSecurity.BearerAuth.class)
default HttpClientTokenProvider bearerAuthTokenProvider() { … }

one per scheme that appears in an operation's security list — including the alternatives that operation never actually takes, because the generated interceptor's constructor asks for every scheme in every alternative. A scheme declared under components/securitySchemes but referenced by no operation needs nothing.

That interceptor evaluates the alternatives in declaration order and uses the first one whose providers all returned non-null. So a provider for an alternative you do not use must return null — otherwise it wins and the request goes out with the wrong header. If no alternative comes out complete, the request is forwarded with no credential and a single WARN Security schema is defined for api but no data was provided.

For http / oauth2 / openId schemes the returned string becomes the whole Authorization header value, so a Bearer provider returns "Bearer " + token, not the bare token.

Everything else about generated clients — config paths, ApiSecurity tag names, the security config prefix — belongs to kora-openapi-generator-client.

8. Do not log the credential

Client telemetry is off by default in Kora 2.0 (telemetry.logging.enabled and telemetry.metrics.enabled default to false; tracing defaults to true). Turning client logging on is what exposes headers:

httpClient.serviceA.telemetry.logging.enabled = true

The client logger masks headers through maskHeaders, whose default is ["authorization", "set-cookie", "cookie"]. Two source-verified traps:

• Setting maskHeaders replaces the default, it does not extend it. Adding "x-api-key" alone silently unmasks authorization. List the defaults again alongside your own.
• Header names are lower-cased when stored, and the mask set is matched against the stored name. maskHeaders = ["X-API-KEY"] never matches and the key is logged in clear text.

An API key in a query parameter is not masked by anything by default — maskQueries starts empty. Add the parameter name (lower-case) if you enable logging.

9. Pitfalls

10. Testing

Swap the provider through KoraAppTestGraphModifier so no token endpoint is called:

@KoraAppTest(Application.class)
class SecureApiClientTest implements KoraAppTestGraphModifier {

    @Override
    public KoraGraphModification graph() {
        return KoraGraphModification.create()
                .replaceComponent(HttpClientTokenProvider.class, () -> (HttpClientTokenProvider) request -> "test-token");
    }

    @Test
    void sendsAuthorization(@TestComponent SecureApiClient client) {
        assertThat(client.getResource()).isNotNull();
    }
}

@TestComponent targets fields and parameters only — it injects a component out of the graph, it does not declare one. Asserting that the header actually reached the server needs a stub upstream; see kora-testing-junit-java and kora-testing-blackbox.

References & assets

Every template exists in both languages and is verified by compiling the generated output against the published 2.0.0.RC1 artifacts (javac 25, Kotlin 2.4.10).

Basic auth, API-key and static-Bearer wiring have no templates on purpose — each is one line inside a @Module you already own:

new BasicAuthHttpClientInterceptor(config.username(), config.password());
new ApiKeyHttpClientInterceptor(ApiKeyHttpClientInterceptor.ApiKeyLocation.HEADER, "X-API-KEY", config.apiKey());
new BearerAuthHttpClientInterceptor(config.token());

Related skills

• kora-http-client — the client itself: routes, mappers, transports, timeouts
• kora-http-server-auth — the inbound side
• kora-openapi-generator-client — generated ApiSecurity
• kora-config-hocon — @ConfigSource, ${VAR} substitution
• kora-json — @Json / @JsonField on token-endpoint payloads
• kora-telemetry-logging — enabling and shaping client logs
• kora-di-compile — @Component, @Module, @Tag, graph errors

Source of truth

There is no Kora 2.0 documentation site. The published docs and every branch of kora-docs, including its docs/v2 directory, describe 1.x in ru.tinkoff.kora terms — usable as conceptual background, never as a 2.0 API authority. This skill was verified against:

• Framework source, tag 2.0.0.RC1: http-client-common (auth/, interceptor/, request/, telemetry/) · http-common (annotation/InterceptWith, telemetry/MaskingUtils) · http-client-annotation-processor
• Migrated examples, branch migration/2.0: kora-java-http-client · kora-kotlin-http-client · kora-java-openapi-generator-http-client
• Migrated guide apps, branch migration/2.0: kora-java-guide-http-client-advanced-app · kora-kotlin-guide-http-client-advanced-app