OIDC & Issuer Trust

This page covers OIDC/JWT issuer trust configuration for KalamDB.

Use this when you want KalamDB to accept tokens from external identity providers (Keycloak, Auth0, Google, Azure AD, etc.).

Token Routing Model

KalamDB inspects every bearer token before signature verification to decide how to validate it:

ES512 is not supported.

This means external tokens from standard OIDC providers are validated natively — no bridge service required.

server.toml Settings

[authentication]
jwt_secret = "replace-with-strong-random-secret-32-plus-chars"
jwt_trusted_issuers = "https://issuer.example.com"
auto_create_users_from_provider = false

Notes:

• [auth] and [authentication] are both accepted (serde alias).
• jwt_trusted_issuers accepts a comma-separated list for multiple issuers.
• Keep jwt_secret strong even when using external issuers — it is still used for internal HS256 tokens from POST /v1/api/auth/login.
• Set auto_create_users_from_provider = true to auto-provision users when a valid external token arrives for an unknown user.

Environment Variable Overrides

export KALAMDB_JWT_SECRET="replace-with-strong-random-secret-32-plus-chars"
export KALAMDB_JWT_TRUSTED_ISSUERS="https://issuer.example.com,https://issuer-2.example.com"
export KALAMDB_AUTH_AUTO_CREATE_USERS_FROM_PROVIDER=true

Boolean env vars accept "true", "1", or "yes" (case-insensitive).

Environment variables override server.toml values.

Full OIDC Configuration Matrix

OIDC Discovery Flow

When KalamDB encounters an external token (non-HS256):

1. Extracts alg and kid from the JWT header (unverified).
2. Extracts iss from the JWT payload (unverified).
3. Confirms iss is in jwt_trusted_issuers.
4. Fetches {issuer_url}/.well-known/openid-configuration.
5. Extracts jwks_uri from the discovery response.
6. Fetches the JWKS endpoint and caches keys by kid.
7. Matches the token kid to a cached signing key.
8. Validates signature, issuer, expiry, and audience (if configured).

JWKS Caching Behavior

• Keys are cached per-issuer in memory, indexed by kid.
• Cache-miss refresh: if a token’s kid is not found, KalamDB automatically re-fetches the JWKS endpoint.
• No TTL-based eviction: cache refreshes only on miss — keys remain cached until an unknown kid triggers a refresh.
• Keys without a kid field are silently discarded from the cache.
• Key rotation at the provider is handled automatically (new kid → cache miss → refresh).

JWT Claims Structure

KalamDB reads these claims from external tokens:

Provider-Agnostic Checklist

1. Confirm exact issuer URL (trailing slashes matter).
2. Verify the provider publishes /.well-known/openid-configuration.
3. Add the issuer URL to jwt_trusted_issuers.
4. Restart KalamDB.
5. Send a provider-issued bearer token to a protected endpoint.
6. Validate authentication and user mapping behavior.

Troubleshooting

Provider Guides

• Keycloak Integration

Related

• Authentication & Bootstrap
• OpenTelemetry (OTEL)