How to manage Firebase custom claims without losing user context
A safety-focused guide to reviewing and editing Firebase custom claims while keeping Auth identities, tenants, and Firestore profiles connected.
Firebase custom claims are compact authorization data attached to an Authentication user. Because applications often use them to grant roles or tenant access, editing a claim is a security-sensitive operation rather than a cosmetic profile change.
Identify the correct user and tenant first
Search with a stable identifier such as UID or an exact email address. In a multi-tenant project, verify the tenant as well as the project. Similar identities can exist in different tenant scopes, and the selected UI row alone should not be the only target signal.
Review the complete claim object
Claims are replaced as an object by common Admin SDK workflows. Adding one role without preserving existing keys can remove unrelated authorization state. Read the current object, validate its shape, and preview the complete replacement.
Keep claims small and authorization-focused
Use claims for compact authorization facts such as a role or tenant identifier. Store larger application profiles in Firestore, where they can be queried and updated independently. Keep the mapping between the Auth identity and profile explicit.
Plan for token refresh
A successful admin update does not immediately alter an already-issued ID token. The application must receive a refreshed token before new claims appear. Support instructions should distinguish “claim saved” from “client session refreshed.”
Use a production checklist
- Confirm project, environment, tenant, UID, and email.
- Compare current and proposed claim JSON.
- Validate allowed keys and value types.
- Record who requested the change and why.
- Explain the token-refresh requirement.
The Firebase Auth admin GUI page shows how Firestruct keeps claims, providers, profile fields, and linked Firestore context together.