Oidc Auth

Karapace OIDC & Auth — Architecture Reference

Karapace ships two services (Schema Registry on FastAPI, REST Proxy on aiohttp) with three independent auth systems that interact in specific ways:

1. SR OIDC — SR validates bearer JWTs against the IdP's JWKS endpoint (authn) and optionally enforces role-based authz.
2. SR Basic Auth — file-based users + ACLs, selected when registry_authfile is set; coexists with OIDC but the two don't run together in the same request pipeline.
3. RP OIDC pass-through — RP does not validate tokens itself. Kafka brokers validate OAUTHBEARER tokens for topic ops; SR validates the same token for schema ops. RP only forwards the inbound Authorization header to SR.

This file is the load-bearing context for those flows. Anchors below are file paths + symbol names (class/function/identifier) — line numbers are deliberately omitted because they rot. When you need a precise location, grep for the symbol.

1. SR OIDC — Token Validation

Files

• src/karapace/api/oidc/validator.py — OIDCTokenValidator (validation + authz)
• src/karapace/api/middlewares/__init__.py — HTTP middleware that runs the gate (_authenticate_and_authorize, setup_middlewares)

Validation flow — OIDCTokenValidator.validate_jwt

1. PyJWKClient.get_signing_key_from_jwt(token) fetches the signing key (cached).
2. jwt.decode() with:
   • algorithms=["RS256","RS384","RS512"] (hardcoded, RSA only)
   • audience — comma-separated sasl_oauthbearer_expected_audience is split into a list
   • issuer — sasl_oauthbearer_expected_issuer
   • options={"require": ["exp","iss","aud"]} — PyJWT does not require these by default; we do, explicitly.
3. ExpiredSignatureError → custom TokenExpiredError (subclass of AuthenticationError) so the 401 reason can say "Token expired" vs. "Invalid token/payload".

JWKS client cache — OIDCTokenValidator.__init__ (self._jwks_client)

PyJWKClient(self.jwks_url, cache_keys=True, lifespan=300, max_cached_keys=16)

• lifespan=300 caps how long a key stays cached after IdP key rotation/revocation.
• max_cached_keys=16 — IdPs typically expose 1-3; 16 is generous.

HTTPS enforcement — OIDCTokenValidator.__init__ (search for allow_insecure_jwks)

JWKS over plain HTTP is rejected unless sasl_oauthbearer_allow_insecure_jwks=true (dev-only override; logs a loud warning). Reason: an in-path attacker could swap signing keys and forge valid tokens.

Subject exposure — _authenticate_and_authorize (search for request.state.user)

After validation, only the configured subject claim (claim_name, default "sub") is set on request.state.user. The full payload is intentionally not exposed to handlers — prevents downstream code from picking up attacker-controlled claims like roles and using them for authz decisions.

Skip paths — setup_middlewares (search for skip_auth_paths)

• Always skipped: /docs, /docs/oauth2-redirect, /redoc, /openapi.json
• Configurable skip: sasl_oauthbearer_skip_auth_paths (default ["/_health", "/metrics"])

2. SR OIDC — Authorization (RBAC)

Flow — OIDCTokenValidator.authorize_request

• Off when sasl_oauthbearer_authorization_enabled=false — returns True immediately.
• Looks up allowed roles for the request method in sasl_oauthbearer_method_roles, e.g. {"GET": ["reader","admin"], "POST": ["admin"], ...}.
• Extracts user roles via sasl_oauthbearer_roles_claim_path (dot-path, e.g. realm_access.roles, or a literal Keycloak path resource_access.<client>.roles).
• Mismatch (or any misconfig) → 403 with the same body as a real role mismatch. This is intentional — an attacker with a valid token must not be able to distinguish "bad config" from "missing role" via response differences.

Required config when authz is on (OIDCTokenValidator.__init__)

• sasl_oauthbearer_roles_claim_path

Missing it → ValueError at startup (fail-closed).

Canonical role names — src/karapace/core/constants.py

Role strings are prefixed karapace. (e.g. karapace.schema:read) and defined as OIDC_ROLE_* constants. DEFAULT_OIDC_METHOD_ROLES maps HTTP methods to them and is the config default for sasl_oauthbearer_method_roles. These must match the roles the IdP mints into tokens — the reference Keycloak realm (container/keycloak/realm-export.json) defines the same set. Change role names in the constants module, keep the realm export and container/compose.yml in sync.

Backwards-compat shim — Config._enforce_authn_when_authz_enabled

If sasl_oauthbearer_authorization_enabled=true but sasl_oauthbearer_authentication_enabled=false, we auto-enable authn and log a deprecation warning. Authz without authn is meaningless; the prior single-flag config is preserved with a warning so operators migrate.

3. RP → SR Token Forwarding

This is the heart of the recent work (commit 27b61e11 "Handle token fwd from rest proxy to sr", merged 2026-05-20 in PR #1287). Read this section before touching anything that crosses the RP/SR boundary.

The contextvar — sr_authorization_ctx in src/karapace/core/serialization.py

sr_authorization_ctx: contextvars.ContextVar[str | None] = contextvars.ContextVar("sr_authorization", default=None)

• Asyncio-safe per-request slot. Threads/locals don't work because asyncio runs many coroutines on one thread.
• None (default) means "no forwarded token" → SchemaRegistryClient falls back to session_auth (the registry_user/registry_password basic-auth pair), which is the legacy behavior.

Where the contextvar is set (RP side, src/karapace/kafka_rest_apis/__init__.py)

Only two entry points set it, both gated on config.sasl_oauthbearer_authentication_enabled:

• UserRestProxy.publish()
• UserRestProxy.fetch()

To find every site, grep: rg 'sr_authorization_ctx\.set'.

if self.config.sasl_oauthbearer_authentication_enabled:
    sr_authorization_ctx.set(request.headers.get("Authorization"))

Why only these two? They're the RP endpoints that internally trigger schema lookups via SchemaRegistryClient. Other RP endpoints (offsets, broker info, consumer create/delete, etc.) don't reach the schema client, so forwarding would be wasted. If you add a new RP endpoint that hits the schema client, set the contextvar there too — there's a comment on the contextvar reminding you of this list.

Where the contextvar is read (SR client side, src/karapace/core/serialization.py)

• _authorization_headers() — returns {"Authorization": auth} or None.
• All SchemaRegistryClient outbound calls merge it into headers:
  • post_new_schema() — merges with Content-Type: application/vnd.schemaregistry.v1+json (the merge matters: Client.post only injects the vendor content-type when headers is falsy; if you pass auth without merging, the request silently demotes to application/json).
  • _get_schema_recursive() and get_schema_for_id() — pass headers=_authorization_headers().

To audit every call site, grep: rg '_authorization_headers\('.

What "RP doesn't validate" actually means

RP only decodes the JWT without verifying the signature to read exp — see get_expiration_timestamp_from_jwt in src/karapace/kafka_rest_apis/authentication.py:

jwt.decode(token, options={"verify_signature": False}).get("exp")

This exp is used only to evict the per-user proxy when the token expires. SR's sasl_oauthbearer_* validation fields don't apply on RP — Kafka validates signature/issuer/audience at the broker, SR validates them again for schema ops.

4. Schema-Client Cache Partitioning by Token Fingerprint

Why

The SchemaRegistryClient LRU caches (subject, version) → (id, schema, version). Without partitioning, a request with no auth could hit a cache slot warmed by an authenticated request — effectively bypassing SR's gate. Conversely, two principals with different roles must not share a slot.

Fingerprint — _token_fingerprint() in src/karapace/core/serialization.py

def _token_fingerprint() -> str:
    auth = sr_authorization_ctx.get()
    if not auth:
        return ""
    return hashlib.sha256(auth.encode("utf-8")).hexdigest()[:16]

• SHA-256, truncated to 16 hex chars. Never log the raw token; never store the raw token in the LRU.
• Empty string is the sentinel for unauthenticated (covers session_auth fallback paths).

Cache key

(subject, version, _token_fingerprint()) → (SchemaId, ValidatedTypedSchema, Version)

Per-instance decoration so cache size is configurable:

self._get_schema_cached = alru_cache(maxsize=cache_maxsize)(self._get_schema_cached)

Tunable

Config.schema_registry_client_cache_maxsize (default 100). Raise for multi-tenant deployments — each principal gets its own cache slot per (subject, version), so heavy fan-out can blow the LRU.

Known limitation

Cache does not invalidate on token revocation — schema bytes are immutable, so a cached (subject, version, fp) entry is still correct material; it just means a revoked token's cache entry will live up to the LRU eviction window. SR re-validates the token on every request before any cache lookup happens (the gate runs in HTTP middleware, before the route handler), so this is benign for authn purposes.

5. SR Basic Auth (Coexistence)

Files

• src/karapace/core/auth.py — HTTPAuthorizer, User, ACLEntry, Operation
• src/karapace/core/config.py — get_authorizer (selector)

Selection — get_authorizer

return http_authorizer if config.registry_authfile else no_auth_authorizer

• registry_authfile set → HTTPAuthorizer (basic auth from JSON file).
• Unset → NoAuthAndAuthz (no-op).

Auth file format (auth.py)

{
  "users": [
    {"username": "...", "algorithm": "sha512", "salt": "...", "password_hash": "..."}
  ],
  "permissions": [
    {"username": "...", "operation": "Read|Write", "resource": "<regex>"}
  ]
}

• Algorithms: sha1, sha256, sha512, scrypt.
• Write implies Read. resource is a regex pattern matched against the resource path.
• File is hot-reloaded via watchfiles.awatch() — edits take effect without restart.

Basic Auth ↔ OIDC orthogonality

• They are independent systems — different config paths, different code paths.
• OIDC runs as Starlette HTTP middleware (before routing).
• Basic Auth runs through the FastAPI dependency injection layer in route handlers.
• A deployment can enable either, both (technically), or neither. In practice, OIDC-on deployments don't set registry_authfile. Tests use distinct fixtures: registry_async_client_oidc (Bearer) vs registry_async_client_basic (BasicAuth).

6. Config Reference — fields on Config in src/karapace/core/config.py

All env vars are prefixed KARAPACE_ (Pydantic BaseSettings). The flag double-duty of sasl_oauthbearer_authentication_enabled (gates BOTH SR validation AND RP forwarding) is deliberate — it means an OIDC-enabled deployment is consistent across both services with a single switch.

7. Tests — where to look

The reset_sr_authorization_ctx fixture is required for any test that touches sr_authorization_ctx — contextvars persist across tests in the same event-loop scope and will leak state otherwise.

RBAC e2e needs a reduced-role Keycloak client

The realm's default karapace-client service account is granted all roles, so it can never be denied. RBAC-denial e2e tests use karapace-client-limited (defined in container/keycloak/realm-export.json), whose service account is assigned only karapace.schema:read + schema:write under karapace-client's role container — so the minted token carries them at the SR's configured resource_access.karapace-client.roles path but lacks delete/config. Keycloak imports the realm only on a fresh container, so recreate keycloak (not just restart) after editing realm-export.json.

No hardcoded secrets in tests

The e2e oidc_token fixture is env-driven (OIDC_PROVIDER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_TOKEN_URL, OIDC_SCOPE, OIDC_REALM, OIDC_VERIFY_TLS); Keycloak secrets are fetched at runtime via the admin API. Never commit a literal Basic <base64> header or client secret — encode at runtime instead. The canonical convention lives in CONTRIBUTING.md ("Secrets and credentials in tests").

8. Mental model when extending

When you add a feature that crosses the auth boundary, walk through these checks:

1. New SR route? It's automatically gated by setup_middlewares. If it should be public, add it to sasl_oauthbearer_skip_auth_paths. Don't read claims other than the configured subject off request.state — only request.state.user is exposed deliberately.
2. New RP endpoint that calls SchemaRegistryClient? Set sr_authorization_ctx from the inbound Authorization header, gated on config.sasl_oauthbearer_authentication_enabled. Update the comment on the contextvar listing the entry points.
3. New SchemaRegistryClient outbound call? Pass headers=_authorization_headers() (or merge it if you already have headers — see the post_new_schema content-type pitfall).
4. New cacheable schema lookup? Include _token_fingerprint() in the cache key. Don't store the raw token anywhere.
5. New authz rule? Prefer extending sasl_oauthbearer_method_roles over inventing a parallel system. If you must inspect the JWT payload, do it inside OIDCTokenValidator — don't leak the payload to handlers.
6. Error responses on auth failure? Match the existing pattern: 401 with {"error": "Unauthorized", "reason": "..."} for authn, 403 with {"error": "Authorization error", "reason": "Forbidden"} for authz. Keep the 403 body identical to the misconfig branch — see OIDCTokenValidator.authorize_request for the rationale (do not let the response distinguish bad config from a missing role).