Skip to Content
AuthenticationAuto-Provisioning Users

Auto-Provisioning Users

KalamDB’s current OIDC model has two distinct paths:

  • regular external users can authenticate directly from validated token claims
  • elevated or explicit external users are stored locally with issuer and subject

That means auto-provisioning is not just “create a row on first login” anymore. For the common user role path, KalamDB can stay stateless after checking whether a local row already exists for the OIDC subject.

Enable Auto-Provisioning

TOML
[auth]jwt_trusted_issuers = "kalamdb,https://idp.example.com/realms/kalamdb" [auth.oidc]enabled = trueissuer = "https://idp.example.com/realms/kalamdb"client_id = "kalamdb"scopes = ["openid", "email", "profile"]auto_provision = truedefault_role = "user"

Environment variable form:

BASH
export KALAMDB_JWT_TRUSTED_ISSUERS="kalamdb,https://idp.example.com/realms/kalamdb"export KALAMDB_AUTH_OIDC_ENABLED=trueexport KALAMDB_AUTH_OIDC_ISSUER="https://idp.example.com/realms/kalamdb"export KALAMDB_AUTH_OIDC_CLIENT_ID="kalamdb"export KALAMDB_AUTH_OIDC_SCOPES="openid,email,profile"export KALAMDB_AUTH_OIDC_AUTO_PROVISION=trueexport KALAMDB_AUTH_OIDC_DEFAULT_ROLE="user"

If auth.oidc.auto_provision = false, authentication succeeds only when a matching local OIDC user already exists.

What Happens For Regular Users

When these conditions are both true:

  • auth.oidc.auto_provision = true
  • auth.oidc.default_role = "user"

KalamDB uses the OIDC sub claim directly as the KalamDB user_id.

Regular users resolve from validated token claims when no persisted system.users row exists for that subject. KalamDB checks the row first so explicit persisted OIDC users, deleted users, and same-ID local password users keep their local policy.

What Still Gets Persisted

Persisted local state is still important for:

  • elevated users such as service, dba, or system
  • soft-deleted external users that must remain blocked
  • deployments with auto_provision = false
  • deployments that intentionally use a default role other than user

Persisted OIDC users store only this identity binding:

JSON
{  "issuer": "https://idp.example.com/realms/kalamdb",  "subject": "provider-subject"}

For persisted OIDC users, subject must match system.users.user_id.

Pre-Create Or Elevate An OIDC User

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

Use explicit provisioning when you need:

  • pre-approved access only
  • an elevated role before first login
  • no end-user auto-provisioning in production

What Happens When The User Does Not Exist

If auth.oidc.auto_provision = false, the first request for an unknown external identity fails even when the provider token itself is valid.

That is expected. Token validation and user mapping are separate steps.

Identity Stability Rules

KalamDB uses the token subject as the user ID, not the email address and not a provider code.

That means:

  • changing email at the provider does not change the KalamDB user ID
  • a different issuer or provider may emit a different subject for the same person
  • deleting and recreating a provider-side account can create a new subject and therefore a new KalamDB user ID
  1. Enable trusted issuers.
  2. Turn on auth.oidc.auto_provision = true for normal end users.
  3. Keep elevated roles explicit.
  4. Check the created identity with GET /v1/api/auth/me or SELECT CURRENT_USER();.
  5. Promote only the accounts that need broader access.
Last updated on
Token AuthOIDC Model