Authenticate a KalamDB Application

Sign in with a local account or your identity provider, then pass that identity to SQL and live subscriptions. Keep administrative credentials out of browser and mobile bundles.

Try KalamDB local authentication

After first-time server setup, create a normal application user as an administrator. This password is a local example; choose your own for a real account:

1CREATE USER 'alice' WITH PASSWORD 'LocalExample123!' ROLE user;

In a Node.js development script, supply that user’s password through the environment:

1import { Auth, createClient } from '@kalamdb/client';2 3const client = createClient({4  url: 'http://127.0.0.1:2900',5  authProvider: async () => Auth.basic('alice', process.env.KALAM_PASSWORD!),6});7 8console.log(await client.query('SELECT CURRENT_USER;'));9await client.disconnect();

Expect the effective user identity in the query result. For a browser, use a sign-in flow and a token provider instead of embedding this password in source code. See the TypeScript authentication guide, Rust authentication, or Dart authentication for refresh and lifecycle handling.

Connect an external provider: Dex example

KalamDB uses one configured external OpenID Connect issuer. Dex is a reproducible local example; Keycloak and other compatible OIDC providers use the same issuer/client configuration model.

The KalamDB repository contains a local Dex setup:

1cd KalamDB/docker/utils2docker compose up -d dex

Merge these settings into the server’s server.toml, preserving its other configuration:

1[auth]2jwt_trusted_issuers = "kalamdb,http://127.0.0.1:5556"3 4[auth.local]5enabled = true6 7[auth.oidc]8enabled = true9display_name = "Dex"10issuer = "http://127.0.0.1:5556"11client_id = "client"12scopes = ["openid", "email", "profile"]13auto_provision = true14default_role = "user"

Restart the server. The repository’s Dex client permits the Admin UI callback http://127.0.0.1:2900/ui/oauth/callback and CLI browser callback http://127.0.0.1:8787/callback. Open the Admin UI and select Dex, or run:

1kalam login --instance local --url http://127.0.0.1:2900 --oidc2kalam --instance local -c 'SELECT CURRENT_USER;'

The bundled local Dex test account is alice@example.org with password kalamdb123. These are development fixtures, not deployment credentials. See Dex setup for the full configuration and device-login options.

Pass the provider identity to your SDK

After your application’s OIDC login flow returns the trusted ID token:

1import { Auth, createClient } from '@kalamdb/client';2 3const client = createClient({4  url: 'https://database.example.com',5  authProvider: async () => Auth.jwt(await getFreshIdToken()),6});

getFreshIdToken() belongs to your identity-provider integration; it must return a valid, refreshed token rather than a hardcoded token. The issuer must match the server configuration and the audience must match its client/audience settings. Use HTTPS for deployed issuers, callbacks, and API endpoints.

KalamDB validates the token and maps the OIDC subject to the effective user. That identity determines USER-table isolation and CURRENT_USER in RLS policies. Do not grant every provisioned account an administrative role to work around an authorization error.

Check the complete flow

1. Sign in as a normal user and query CURRENT_USER.
2. Write and read that user’s data.
3. Sign in as a second user and verify isolation.
4. Open a live subscription with the same identity.
5. Test token refresh and sign-out; stop old subscriptions when accounts change.

For another provider, replace the issuer, client ID, allowed callbacks, and audience with that provider’s values. KalamDB supports one external issuer per process; multiple tenants/providers require an intentional identity-broker design.

Next step

Protect shared data with row-level security →

Reference: OIDC configuration and issuer trust.