Dex

Dex is the simplest supported way to test KalamDB’s current OIDC flow locally.

Use Dex when you want:

• a small standards-compliant OIDC issuer for local development
• repeatable browser and device-flow testing for the Admin UI and CLI
• a test IdP that matches KalamDB’s single-provider OIDC model

Local Dex Setup

The KalamDB repo already includes a Dex container and config:

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

Default local Dex values from the shared development config:

• issuer: http://127.0.0.1:5556
• public client ID: client
• Admin UI callback: http://127.0.0.1:2900/ui/oauth/callback
• CLI browser callback: http://127.0.0.1:8787/callback
• test user: alice@example.org
• test password: kalamdb123

KalamDB server.toml Example

1[auth]2jwt_secret = "replace-with-a-strong-random-secret-at-least-32-chars"3jwt_trusted_issuers = "kalamdb,http://127.0.0.1:5556"4allow_remote_setup = false5cookie_secure = false6 7[auth.local]8enabled = true9 10[auth.oidc]11enabled = true12display_name = "Dex"13issuer = "http://127.0.0.1:5556"14client_id = "client"15scopes = ["openid", "email", "profile"]16auto_provision = true17default_role = "user"18broker_device_flow_enabled = false19device_authorization_endpoint = "http://127.0.0.1:5556/device/code"

For the public Dex client used in local development, leave client_secret unset.

Admin UI Login

Make sure the Dex client allows this redirect URI:

1http://127.0.0.1:2900/ui/oauth/callback

Then open the Admin UI, choose the OIDC login button, and sign in as alice@example.org with password kalamdb123.

CLI Login

Browser login

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

This uses the local browser callback at http://127.0.0.1:8787/callback.

Direct device login

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

Use this when you want to stay headless and let the CLI complete provider device flow directly.

Brokered device login

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

Enable brokered mode only when the CLI host cannot reach Dex directly but can reach KalamDB.

Notes On Production Use

Dex can be used beyond local development, but production use is an operational choice, not a KalamDB requirement.

Dex is a good fit when:

• you control the deployment environment
• you manage TLS, connector configuration, storage, and backups yourself
• you want a lightweight self-hosted OIDC layer

Many teams still prefer an existing enterprise IdP for production. From KalamDB’s perspective, that is fine because the runtime only cares about one configured OIDC issuer.

Related

• OIDC & Issuer Trust
• Authentication & Bootstrap
• Kalam CLI Command Reference
• OIDC Model