Firebase

KalamDB can accept Firebase Authentication ID tokens directly as bearer tokens.

Clients authenticate with Firebase, receive a Firebase ID token, and send it to KalamDB with:

Authorization: Bearer <firebase-id-token>

How It Works

Firebase ID tokens are signed with RS256 and carry:

• iss = https://securetoken.google.com/{PROJECT_ID}
• aud = {PROJECT_ID}
• sub = Firebase UID

KalamDB treats Firebase as an external OIDC issuer, validates the token, and maps the user to a local username in this form:

oidc:fbs:{firebase-uid}

Required Server Setup

The minimum required settings are the trusted issuer and, if you want audience validation, the Firebase provider issuer and client ID.

[authentication]
jwt_trusted_issuers = "https://securetoken.google.com/YOUR_PROJECT_ID"
auto_create_users_from_provider = true
 
[oauth.providers.firebase]
enabled = true
issuer = "https://securetoken.google.com/YOUR_PROJECT_ID"
client_id = "YOUR_PROJECT_ID"

Environment variables:

export KALAMDB_JWT_TRUSTED_ISSUERS="https://securetoken.google.com/YOUR_PROJECT_ID"
export KALAMDB_AUTH_AUTO_CREATE_USERS_FROM_PROVIDER=true

Replace YOUR_PROJECT_ID with the Firebase project ID, not the full app domain.

Notes About Discovery And Validation

KalamDB’s current bearer-token path uses standard OIDC discovery from the issuer URL and then fetches the provider JWKS. For Firebase, that means the issuer must be exact and reachable.

If client_id is configured for oauth.providers.firebase, KalamDB also validates aud against your Firebase project ID.

First Login Behavior

With auto_create_users_from_provider = true, the first valid Firebase request creates a local user automatically as role user.

If you keep auto-provisioning disabled, create the user yourself before first login:

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

Client Example

Web

import { getAuth } from "firebase/auth";
 
const auth = getAuth();
 
async function queryKalamDB(sql: string) {
  const user = auth.currentUser;
  if (!user) throw new Error("Not signed in");
 
  const idToken = await user.getIdToken();
 
  const response = await fetch("https://your-kalamdb-host/v1/api/sql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${idToken}`,
    },
    body: JSON.stringify({ sql }),
  });
 
  return response.json();
}

cURL

TOKEN="<firebase-id-token>"
 
curl -X POST https://your-kalamdb-host/v1/api/sql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT CURRENT_USER();"}'

Token Refresh

Firebase manages token refresh on the client side. Call getIdToken() near request time so the SDK can return a fresh token when needed.

KalamDB does not mint refresh tokens for Firebase identities.

Troubleshooting

401 or 403 issuer not trusted

The Firebase issuer is missing or does not exactly match the token iss claim.

[authentication]
jwt_trusted_issuers = "https://securetoken.google.com/YOUR_PROJECT_ID"

401 audience mismatch

oauth.providers.firebase.client_id must match the Firebase project ID.

404 user not found or invalid credentials after validation

The token is valid, but there is no local user mapping and auto-provisioning is off. Enable auto_create_users_from_provider or pre-create the oidc:fbs:{uid} user.

Inspect token claims

echo "<TOKEN>" | cut -d. -f2 | base64 -d 2>/dev/null | jq '{iss,aud,sub,email,exp}'

Related

• Authentication Overview
• Token Auth
• Auto-Provisioning Users
• OIDC & Issuer Trust