After your backend sets a Firebase Authentication custom claim with setCustomUserClaims, why does the Android app not see it, and how do you fix it?
answer
- claims live inside the token
- tokens are immutable once issued
- new token: sign-in, hourly refresh, force
- getIdToken(true) after the server says done
- overwrite, 1000 bytes, access only
basics
~20 sCustom claims travel inside the ID token, and the token on the phone was issued before the change. They appear only in the next token: at sign-in, at the hourly refresh, or when the app calls getIdToken(true) after the backend confirms.
solid answer
~50 s`setCustomUserClaims(uid, claims)` updates the user record, but the claims reach clients only inside **ID tokens**, and the token the phone holds was issued before the change. A new token picks them up when the user signs in or re-authenticates, when the SDK refreshes an expired token (up to an hour later), or when the app forces a refresh with `getIdToken(true)`. So have the backend answer success after setting the claim, and on success call `getIdToken(true)` and read `result.claims`; for changes the client did not start, the backend can write a marker the app listens to. Mind the API: it **overwrites** all existing claims, the serialized payload must stay within 1000 bytes, and claims are for access control only. The app may read them to adjust the UI, but the backend must enforce access from a token it verified.
code
typescript · 9 linesimport { getAuth } from "firebase-admin/auth";
export async function grantPremium(uid: string): Promise<void> {
const auth = getAuth();
const user = await auth.getUser(uid);
// setCustomUserClaims replaces the whole object, so merge with what is there.
const claims = { ...(user.customClaims ?? {}), premium: true };
await auth.setCustomUserClaims(uid, claims); // serialized JSON must stay within 1000 bytes
}go deeper
Know that custom claims are set by a server with the Admin SDK and arrive in the user's ID token, which the app can read.
Explain the three moments a new token picks up claims, and the getIdToken(true) handshake after the backend confirms the change.
Handle the sharp edges: overwrite semantics and racing writers, the 1000-byte limit, downgrades that linger for an hour, and enforcing on the backend instead of in the UI.
Decide which access decisions belong in claims and which in a database lookup, given token size, propagation delay and how fast a revoked privilege must disappear.
## What custom claims are **Custom claims** are key-value pairs that the Admin SDK attaches to a user account and that Firebase copies into every **ID token** it issues for that user. They exist for **access control**: a `premium` flag, an `admin` role, a group or tenant identifier. Because they ride inside a signed token, anything that verifies the token (your backend, Security Rules) can read them without an extra lookup. They are set **only from a privileged server**, with `getAuth().setCustomUserClaims(uid, claims)`. The Android SDK can read them from a token but has no call that writes them. ## Why the app does not see the new claim The claims live in the token, and a token is immutable once issued. `setCustomUserClaims` updates the user record; the ID token already on the phone still carries the old claims. New claims reach the client only when a **new ID token is issued**, which happens when: 1. the user signs in or re-authenticates; 2. the current ID token expires and the SDK refreshes it, up to an hour later; 3. the app forces a refresh with `getIdToken(true)`. So in a notes app, a user who pays for premium can keep seeing the free tier for up to an hour unless you force a refresh. The same holds on every device the user is signed in on: each one picks the claim up at its own next token, so a phone and a tablet can briefly disagree about what the user may do. Nothing about this is an error, and retrying the backend call does not help; only a new token does. ## The fix: tell the client to refresh Firebase documents two patterns: - **Request and response.** The client calls your backend (a purchase, a role change); the backend sets the claims and answers success; on success the client calls `getIdToken(true)` and reads `result.claims`. - **Server-initiated change.** When the change does not start from the client (a scheduled script, an admin tool), the backend also writes a marker, a `refreshTime` value in Realtime Database in Firebase's example, that the signed-in client listens to and answers with `getIdToken(true)`. On the client, read claims from `GetTokenResult.claims` only to adjust the UI. The **backend must enforce** access from claims in a token it verified itself; claims sent to it any other way cannot be trusted. ## setCustomUserClaims rules that bite | Rule | Consequence | |---|---| | The call **overwrites** all existing custom claims | read `getUser(uid).customClaims`, merge, then write | | Passing `null` deletes the user's custom claims | use it to strip every role at once | | The serialized payload may not exceed **1000 bytes** | larger payloads throw `auth/claims-too-large` | | Reserved names (`aud`, `exp`, `sub`, `firebase` and the other OIDC claims) are refused | throws `auth/reserved-claim` | | Values must be JSON-serializable | strings, numbers, booleans, arrays, objects and null | | A custom token's claims win on overlap | a key set at custom-token sign-in overrides the same key set here | ## Two places the server can read claims On the backend there are two views of the same claims, and they can disagree: - **The verified token.** `verifyIdToken` returns the claims as top-level keys of the `DecodedIdToken`, so a `premium` claim is `decoded.premium`. This is what the caller's current session was granted, and it may be up to an hour old. - **The user record.** `getUser(uid).customClaims` returns what is stored now, after the latest `setCustomUserClaims`. Authorize a request from the token it carried, so the backend and Security Rules agree on what the session holds; read the record when you are about to change the claims. ## Keep claims small, and for access only Every authenticated request carries the ID token, so claims inflate every call. Firebase strongly discourages using them for profile data or preferences; keep those in Firestore or another store. Treat a claim as a **cached decision** about access, not as the source of truth: - **Upgrades can afford to be late**: the user waits for the next token, or you force a refresh. - **Downgrades cannot**: removing `admin` leaves it in every outstanding token until that token expires. If that hour matters, also call `revokeRefreshTokens(uid)` and verify sensitive calls with `checkRevoked`. - **Rules follow the same timing**: a rule that reads `request.auth.token.premium` sees the claim only once the client holds a new token; writing such rules is covered with Security Rules.
- Two backend jobs each add a different custom claim to the same Firebase user at the same moment. What can go wrong?Each job reads the current claims, adds its key and writes the whole object back with `setCustomUserClaims`, which overwrites. If both read before either writes, the second write drops the first job's key. Route claim changes for a user through one writer, or re-read and verify after writing.
- Where does an Android app read a user's Firebase custom claims, and what may it do with them?From the `GetTokenResult` of `getIdToken(false)`, or `getIdToken(true)` after a change, via `result.claims`. The app may use them to show or hide UI, such as a premium badge. It must not treat them as authorization for its own backend: the backend reads them from the token it verified.
- Why does Firebase discourage storing a user's display preferences in custom claims?Claims are copied into every ID token, and every authenticated request carries that token, so extra data costs bytes on every call and is capped at 1000 bytes in all. Changes also reach the client only at the next token issue. Preferences belong in Firestore or another store the app reads directly.
- setCustomUserClaims pushes the new claim to signed-in devices immediately.
- setCustomUserClaims merges the new keys into the user's existing claims.
- Custom claims are a good place for profile data and user preferences.
- The app can send its claims to the backend in the request body.
- Removing a claim takes effect at once for tokens already issued.