Custom Claims, Tenant / Role Data, Token Refresh, Revocation, and Avoiding Authorization Only in UI

1. Claims are cached authorization assertions, not a live permissions table

AtlasMart wants support agents to see a support console and call privileged backend actions. A custom claim such as role: "support" is useful because it is cryptographically carried in the Firebase ID token and can be read by Security Rules or a verified backend token. But changing the user record does not mutate already-issued ID tokens. Role changes therefore have a propagation lifecycle, and revocation has separate semantics.

Learning outcomes

2. What custom claims are good for

Firebase custom claims are limited to 1000 bytes and must remain JSON-serializable. More importantly, their intended purpose is access control—not general user metadata.

3. Observe claim propagation in the Auth emulator

process.env.FIREBASE_AUTH_EMULATOR_HOST = "127.0.0.1:9099";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getAuth } from "firebase-admin/auth";initializeApp({ projectId: "demo-atlasmart-firestore" });const auth = getAuth();const uid = "u-support-1";await auth.updateUser(uid, { displayName: "Atlas Support" }).catch(() => {});await auth.setCustomUserClaims(uid, {  tenantId: "t-atlas",  role: "support"});console.log("Claims updated. Existing client ID tokens remain unchanged until refreshed/reissued.");

import { getAuth } from "firebase/auth";const auth = getAuth();const before = await auth.currentUser.getIdTokenResult(false);console.log({  phase: "before-force-refresh",  role: before.claims.role ?? null,  tenantId: before.claims.tenantId ?? null,  issuedAtTime: before.issuedAtTime,  expirationTime: before.expirationTime});const after = await auth.currentUser.getIdTokenResult(true);console.log({  phase: "after-force-refresh",  role: after.claims.role ?? null,  tenantId: after.claims.tenantId ?? null,  issuedAtTime: after.issuedAtTime,  expirationTime: after.expirationTime});// Do not print the raw JWT itself.

The important observation is not the exact token text. Record only decoded fields such as uid, role, tenantId, issue time and expiry. Existing tokens may continue to contain the old role until a new token is issued through sign-in, normal refresh after expiration, or an explicit force refresh.

4. Backend verification is identity input, not the final decision

const decoded = await adminAuth.verifyIdToken(idToken);const actor = {  uid: decoded.uid,  tenantId: decoded.tenantId ?? null,  role: decoded.role ?? "customer",  authTime: decoded.auth_time};// Authorization still follows.if (actor.tenantId !== order.tenantId) throw forbidden("CROSS_TENANT");if (!['support', 'admin'].includes(actor.role)) throw forbidden("ROLE_REQUIRED");

verifyIdToken() validates the token’s signature/shape/expiry and returns decoded claims, but the ordinary verification method does not by itself check refresh-token revocation. When immediate session invalidation matters in production, use the documented revocation mechanism and an appropriate verification strategy rather than assuming claim removal invalidates an already-issued JWT.

5. Simulate revocation locally, understand production revocation separately

// Production Firebase supports revokeRefreshTokens(uid) and verifyIdToken(token, true).// The mandatory local lab instead makes the freshness requirement deterministic.const revokedAfterByUid = new Map();export function revokeLocally(uid, nowSeconds) {  revokedAfterByUid.set(uid, nowSeconds);}export function requireFreshSession(actor) {  const revokedAfter = revokedAfterByUid.get(actor.uid) ?? 0;  if ((actor.authTime ?? 0) <= revokedAfter) {    throw Object.assign(new Error("SESSION_REAUTH_REQUIRED"), { status: 401 });  }}

// Run only in a real controlled Firebase project when immediate revocation is required.await adminAuth.revokeRefreshTokens(uid);try {  const decoded = await adminAuth.verifyIdToken(idToken, true); // checkRevoked = true  // continue authorization} catch (error) {  if (error.code === "auth/id-token-revoked") {    // Ask the client to reauthenticate/sign out.  }  throw error;}

The production revoked-token check requires consulting Firebase Authentication state and adds work compared with normal stateless JWT verification. Apply it according to risk rather than sprinkling it blindly into every endpoint. The mandatory lab uses a deterministic in-memory revocation threshold so learners can test freshness-sensitive authorization without pretending the emulator reproduces every production session mechanism.

6. Wrong approach: put rapidly changing authorization only in claims

Imagine AtlasMart stores refundLimitCents=50000 in a claim and compliance lowers it to 5000 during an incident. Existing tokens may retain the old value until refresh. A safer pattern keeps coarse stable roles in claims and loads highly dynamic/high-risk policy from an authoritative backend store when the action is sensitive enough to justify it.

7. Do not authorize only in the UI

// BAD: UI decides access, backend trusts it.if (tokenResult.claims.role === "support") showRefundButton();// attacker can still call POST /refund directly// GOOD: UI is convenience only; backend repeats authoritative decision.const actor = await verifiedActor(adminAuth, req.headers.authorization);authorizeRefund(actor, order);await performRefund(order);

The UI can use claims to shape navigation, but hidden controls are not a security boundary. Security Rules and backend authorization remain authoritative.

8. Claim test matrix

Production judgment and bridge to Lesson 4

Claims trade lookup cost for bounded staleness. Use them for compact, trusted authorization assertions whose lifecycle you understand. For critical state, combine them with authoritative server checks and explicit session-revocation policy. Lesson 4 turns to the other side of identity—the backend credential itself—and shows how ADC, attached service accounts, impersonation and Workload Identity Federation avoid distributing long-lived private keys.

Knowledge check

1. When do changed custom claims appear in a user’s token?
2. How long do Firebase ID tokens normally last?
3. Does verifyIdToken(token) automatically check that refresh tokens were revoked?
4. Why should fast-changing refund policy not live only in claims?
5. Can a UI role check replace backend authorization?

Summary

Custom claims are signed, compact and useful—but not instantaneous. AtlasMart now distinguishes claim issuance, token refresh, session revocation and application policy freshness instead of treating “role changed” as an immediate global fact.

Authoritative references

• Secure data in Cloud Firestore
• Firestore IAM
• Security Rules conditions and server-library bypass
• Add the Firebase Admin SDK to your server
• Verify Firebase ID tokens
• Custom claims and access control
• Manage user sessions and token revocation
• Connect to the Authentication emulator
• Connect to the Firestore emulator
• How Application Default Credentials works
• Best practices for service accounts
• Workload Identity Federation
• Firestore IAM roles and permissions
• Authenticate and connect with Firestore MongoDB compatibility
• Enterprise Native server client libraries
• Firebase Admin Node.js SDK release notes
• Firebase CLI release notes