Authentication Overview

KalamDB supports password login for local accounts and bearer-token auth for both KalamDB-issued JWTs and external OIDC providers.

Authentication Methods

All bearer tokens go through the same validation pipeline. KalamDB routes internal and external tokens automatically from the JWT algorithm and issuer.

Bearer Token Routing

Client                   Identity Provider            KalamDB
  │                            │                          │
  │── sign in ────────────────►│                          │
  │◄── ID token (RS256) ────────│                          │
  │                            │                          │
  │── Authorization: Bearer <id-token> ─────────────────►│
  │                            │  1. Check iss is trusted │
  │                            │  2. OIDC discovery       │
  │                            │  3. Fetch + cache JWKS   │
  │                            │  4. Verify RS256 sig     │
  │                            │  5. Resolve/provision user│
  │◄── SQL response ────────────────────────────────────── │

KalamDB inspects the token before verification:

1. Algorithm — HS256 → internal shared-secret validation; RS256/ES256/… → external OIDC flow.
2. Issuer (iss) — must appear in jwt_trusted_issuers; untrusted issuers are rejected before any network I/O.
3. JWKS — keys are fetched on first use and cached per-issuer; key rotation is handled automatically.
4. Audience (aud) — validated against client_id in [oauth.providers.*] when configured.

Trusted Issuers

Every external provider must be listed in [authentication].jwt_trusted_issuers:

[authentication]
jwt_trusted_issuers = "https://securetoken.google.com/my-project,https://accounts.google.com"
auto_create_users_from_provider = true

If jwt_trusted_issuers is empty, KalamDB still trusts its internal kalamdb issuer, but rejects external issuers. Add each external issuer explicitly.

User Provisioning

External OIDC users get a deterministic KalamDB username in the format:

oidc:<provider-code>:<subject>

Auto-provision

Enable auto_create_users_from_provider = true to have KalamDB create the user record on first login:

[authentication]
auto_create_users_from_provider = true

Auto-created provider users are created as role user. Promote them later with ALTER USER ... SET ROLE ... if they need elevated access.

Manual provision

CREATE USER WITH
  USERNAME 'oidc:fbs:FIREBASE_UID'
  EMAIL    'alice@example.com'
  ROLE     user
  OAUTH;

Role Management

Provider users created automatically or manually can be upgraded by a DBA at any time:

ALTER USER 'oidc:fbs:FIREBASE_UID' SET ROLE dba;

Supported Algorithms

Provider Guides

• Supported Providers
• Token Auth
• Auto-Provisioning Users
• Firebase
• Keycloak