Authentication Overview

KalamDB has one authentication surface with two modes:

• local username/password login through [auth.local]
• one external OpenID Connect provider through [auth.oidc]

The same API and SDK surfaces work for both:

• POST /v1/api/auth/login
• POST /v1/api/auth/refresh
• GET /v1/api/auth/me
• GET /v1/api/auth/login-options
• bearer auth for /v1/api/sql, files, topics, and WebSocket traffic

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

1Client                   Identity Provider            KalamDB2  │                            │                          │3  │── sign in ────────────────►│                          │4  │◄── ID token (RS256) ────────│                          │5  │                            │                          │6  │── Authorization: Bearer <id-token> ─────────────────►│7  │                            │  1. Check iss is trusted │8  │                            │  2. OIDC discovery       │9  │                            │  3. Fetch + cache JWKS   │10  │                            │  4. Verify RS256 sig     │11  │                            │  5. Resolve/provision user│12  │◄── 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 auth.oidc.audience or auth.oidc.client_id when configured.

Single External OIDC Provider

KalamDB no longer uses a built-in provider enum or a provider matrix. The active external identity model is issuer-based:

1[auth]2jwt_trusted_issuers = "kalamdb,https://idp.example.com/realms/kalamdb"3 4[auth.oidc]5enabled = true6display_name = "Company SSO"7issuer = "https://idp.example.com/realms/kalamdb"8client_id = "kalamdb"9scopes = ["openid", "email", "profile"]10auto_provision = true11default_role = "user"

Examples of issuers that fit this model:

• Dex
• Keycloak
• Okta
• Auth0
• Entra ID
• Google
• Firebase

The important point is that one KalamDB server process supports one configured external OIDC issuer.

Identity Mapping

External users use the OIDC sub claim directly as the KalamDB user_id. There is no provider code, username prefix, or generated hash ID in the active model.

The same subject value appears in SQL identity, system.users.user_id, and PG extension EXECUTE AS USER '<user_id>' workflows. The subject must be a valid KalamDB user ID: ASCII letters, digits, _, or -, up to 128 characters.

When KalamDB persists a local override or explicit OIDC user, it stores only this provider identity data:

1{2  "issuer": "https://idp.example.com/realms/kalamdb",3  "subject": "provider-subject"4}

Auto-Provision vs Explicit Users

When auth.oidc.auto_provision = true and auth.oidc.default_role = "user", regular external users authenticate as role user without a per-user row on the hot path.

KalamDB checks for an existing system.users row with user_id = sub first. That keeps explicit persisted OIDC users, deleted users, and same-ID local password users from being bypassed.

Elevated users still need explicit persisted overrides. Use this when a user must be service, dba, or system:

1CREATE USER 'provider-subject'2  WITH OIDC '{"issuer":"https://idp.example.com/realms/kalamdb","subject":"provider-subject"}'3  ROLE dba4  EMAIL 'alice@example.com';

Browser And Device Login Surfaces

The Admin UI and CLI both discover auth capabilities from GET /v1/api/auth/login-options.

Current user-facing OIDC flows:

• Admin UI browser login through /v1/api/auth/oidc/exchange-code
• CLI browser login with kalam login --oidc
• CLI direct device login with kalam login --oidc --no-browser
• CLI brokered device login with kalam login --oidc --no-browser --brokered

Role Management

Roles remain the same regardless of auth source:

• user: normal app or tenant user
• service: workers, automation, agents
• dba: database administration
• system: highest-privilege internal role

Supported Algorithms

Related

• Single OIDC Provider Model
• Token Auth
• Auto-Provisioning Users
• OIDC & Issuer Trust
• Dex