Auto-Provisioning Users

When a trusted external JWT is accepted, KalamDB still needs a local user record. You can either pre-create that user or let KalamDB create it on first login.

Enable Auto-Provisioning

[authentication]
auto_create_users_from_provider = true
jwt_trusted_issuers = "https://keycloak.example.com/realms/myrealm,https://securetoken.google.com/my-project"

Environment variable form:

export KALAMDB_AUTH_AUTO_CREATE_USERS_FROM_PROVIDER=true
export KALAMDB_JWT_TRUSTED_ISSUERS="https://keycloak.example.com/realms/myrealm,https://securetoken.google.com/my-project"

If auto-provisioning is off, authentication succeeds only when the provider user already exists locally.

What KalamDB Creates

For a first-time external user, KalamDB derives a deterministic username:

oidc:{provider-prefix}:{subject}

Examples:

The backend then creates a local user record with these important properties:

• auth_type = OAuth
• username = oidc:{prefix}:{sub}
• email copied from the token when present
• password_hash left empty
• default role user

That role is important: current provider auto-provisioning creates users as user. If someone needs service, dba, or system, promote them after the first login.

Promote a Provisioned User

ALTER USER 'oidc:kcl:alice' SET ROLE dba;

When Manual Provisioning Is Better

Prefer manual provisioning when you need:

• pre-approved access only
• a specific role before first login
• tighter onboarding for production or admin users

Example:

CREATE USER 'oidc:fbs:FIREBASE_UID'
  WITH OAUTH '{"provider":"firebase","subject":"FIREBASE_UID"}'
  ROLE user
  EMAIL 'user@example.com';

For Keycloak:

CREATE USER 'oidc:kcl:keycloak-subject'
  WITH OAUTH '{"provider":"keycloak","subject":"keycloak-subject"}'
  ROLE user
  EMAIL 'alice@example.com';

What Happens If The User Does Not Exist

If auto_create_users_from_provider = false, the first request for an unknown provider user fails with a user-not-found style auth error.

That is expected behavior. The token can be valid and still be rejected because there is no local user mapping yet.

Provider Matching Rules

KalamDB keys the local account from the token issuer and subject, not from the email address.

That means:

• changing email at the provider does not change the KalamDB username
• a different issuer with the same email becomes a different KalamDB user
• deleting and recreating a provider-side account can create a new subject and therefore a new local identity

Recommended Rollout Pattern

1. Enable trusted issuers.
2. Turn on auto_create_users_from_provider = true for normal end users.
3. Keep elevated roles manual.
4. Check the created identity with GET /v1/api/auth/me or SELECT CURRENT_USER();.
5. Promote only the accounts that need broader access.

Related

• Authentication Overview
• Token Auth
• OIDC & Issuer Trust
• User Management