Skip to Content
Getting StartedAuthentication & Bootstrap

Authentication & Bootstrap

KalamDB now has one authentication surface with two modes:

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

There is no active provider matrix anymore. Dex, Keycloak, Okta, Auth0, Entra ID, Google, Firebase, and similar services all fit the same single-provider OIDC slot as long as they expose standards-compliant discovery metadata.

Use this page for the practical rollout:

  1. bootstrap the server locally
  2. create the initial DBA and root credentials
  3. configure [auth.oidc]
  4. test Admin UI and CLI login
  5. optionally disable local password login after migration

For the full config matrix, see OIDC & Issuer Trust. For a local test IdP, use Dex.

1. Bootstrap The Server

Check whether the server still needs first-time setup:

BASH
curl http://127.0.0.1:2900/v1/api/auth/status

When the response contains "needs_setup": true, create the initial DBA and root password:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d @- <<'JSON'{  "user": "admin",  "password": "AdminPass123!",  "root_password": "RootPass123!",  "email": "admin@example.com"}JSON

Important behavior:

  • POST /v1/api/auth/setup is localhost-only unless auth.allow_remote_setup = true
  • setup creates the initial local admin credentials; it does not return tokens
  • if you plan to disable local auth later, do the bootstrap first while [auth.local].enabled = true

2. Configure Local + OIDC Auth In server.toml

Start with a combined rollout so you keep a local admin escape hatch while validating OIDC:

TOML
[auth]jwt_secret = "replace-with-a-strong-random-secret-at-least-32-chars"jwt_trusted_issuers = "kalamdb,https://idp.example.com/realms/kalamdb"jwt_expiry_hours = 24allow_remote_setup = falsecookie_secure = true [auth.local]enabled = true [auth.oidc]enabled = truedisplay_name = "Company SSO"issuer = "https://idp.example.com/realms/kalamdb"client_id = "kalamdb"client_secret = "optional-confidential-client-secret"scopes = ["openid", "email", "profile"]auto_provision = truedefault_role = "user"broker_device_flow_enabled = true# Optional when discovery does not advertise device flow.device_authorization_endpoint = "https://idp.example.com/realms/kalamdb/protocol/openid-connect/auth/device"

Rules that matter:

  • KalamDB supports one external OIDC provider per server process
  • auth.oidc.issuer and auth.oidc.client_id are required when auth.oidc.enabled = true
  • auth.oidc.scopes must include openid
  • auth.jwt_trusted_issuers should include both kalamdb and the external issuer

Equivalent environment overrides:

BASH
export KALAMDB_AUTH_OIDC_ENABLED=trueexport KALAMDB_AUTH_OIDC_ISSUER="http://127.0.0.1:5556"export KALAMDB_AUTH_OIDC_CLIENT_ID="kalamdb"

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

3. Discover Available Login Methods

The Admin UI and CLI discover auth capabilities from the same endpoint:

BASH
curl http://127.0.0.1:2900/v1/api/auth/login-options

Typical response:

JSON
{  "local": { "enabled": true },  "oidc": {    "enabled": true,    "display_name": "Company SSO",    "issuer": "https://idp.example.com/realms/kalamdb",    "client_id": "kalamdb",    "authorization_endpoint": "https://idp.example.com/.../auth",    "token_endpoint": "https://idp.example.com/.../token",    "device_authorization_endpoint": "https://idp.example.com/.../device",    "scopes": ["openid", "email", "profile"],    "device_flow": {      "direct_supported": true,      "broker_supported": true,      "broker_start_endpoint": "/v1/api/auth/oidc/device/start",      "broker_poll_endpoint": "/v1/api/auth/oidc/device/poll"    }  }}

4. Admin UI Browser Login

For browser login, configure the IdP redirect URI to:

TEXT
https://YOUR_KALAMDB_ORIGIN/ui/oauth/callback

The Admin UI uses Authorization Code + PKCE:

  1. browser fetches /v1/api/auth/login-options
  2. browser redirects to the configured OIDC authorization endpoint
  3. the callback page posts the code and PKCE verifier to /v1/api/auth/oidc/exchange-code
  4. KalamDB verifies the provider response and returns KalamDB access and refresh tokens

5. CLI Login

Local username/password login

BASH
kalam login --instance local --url http://127.0.0.1:2900 --user admin --password

Browser OIDC login

BASH
kalam login --instance local --url http://127.0.0.1:2900 --oidc

For browser OIDC, register this redirect URI at the provider:

TEXT
http://127.0.0.1:8787/callback

Device login without opening a browser callback

BASH
kalam login --instance local --url http://127.0.0.1:2900 --oidc --no-browser

This uses direct provider device flow when the provider exposes a device authorization endpoint.

Brokered device login

BASH
kalam login --instance local --url http://127.0.0.1:2900 --oidc --no-browser --brokered

Use brokered mode when the CLI host cannot reach the provider directly but can reach KalamDB.

Operational notes:

  • successful interactive kalam login continues directly into the SQL shell
  • non-interactive kalam login saves credentials and exits
  • --no-save skips writing credentials to disk

6. Use KalamDB Tokens For API Calls

After local login or OIDC exchange, use the returned KalamDB access token on API calls:

BASH
curl -X POST http://127.0.0.1:2900/v1/api/sql \  -H "Authorization: Bearer <access_token>" \  -H 'Content-Type: application/json' \  -d '{"sql":"SELECT CURRENT_USER();"}'

Use /v1/api/auth/me to confirm the resolved identity:

BASH
curl http://127.0.0.1:2900/v1/api/auth/me \  -H "Authorization: Bearer <access_token>"

7. Auto-Provisioning And Explicit OIDC Users

With auth.oidc.auto_provision = true and auth.oidc.default_role = "user", regular OIDC users authenticate as their OIDC sub without a persisted per-user row when no local row exists.

When you need an elevated role before first login, or when auto_provision = false, pre-create the OIDC user explicitly with issuer and subject:

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

For persisted OIDC users, the CREATE USER id must match the OIDC subject.

8. Disable Local Password Login After Migration

Once OIDC is proven and you still have a safe DBA path, you can disable local password login:

TOML
[auth.local]enabled = false

This disables local username/password login server-side. The Admin UI and CLI also learn that state through /v1/api/auth/login-options and should hide local login controls.

The bridge issuer (e.g. kalamdb-keycloak-bridge) must appear in jwt_trusted_issuers.

8. Production Hardening

Before exposing KalamDB publicly:

  1. Set strong auth.jwt_secret (or KALAMDB_JWT_SECRET).
  2. Keep auth.allow_remote_setup = false.
  3. Set auth.cookie_secure = true behind HTTPS.
  4. Configure auth.jwt_trusted_issuers when using external IdPs.
  5. Tune rate_limit.max_auth_requests_per_ip_per_sec.

For full endpoint auth behavior, see HTTP API Reference.

Last updated on
AI Agent Coding GuidelinesConfiguration