Firexport / Anleitungen

Benutzerdefinierte Claims in Firebase Authentication festlegen

Benutzerdefinierte Claims (Custom Claims) sind Werte wie admin: true, die Sie einem Firebase-Nutzer zuordnen und die im ID-Token des Nutzers mitgeschickt werden. Über sie geben die meisten Apps einem Nutzer eine Rolle, die Sicherheitsregeln und ein Backend prüfen können. Die Firebase Console kann sie nicht festlegen und zeigt sie nicht einmal an: Authentication > Nutzer (Users) hat kein Feld für Claims. Festgelegt werden sie mit dem Admin SDK, und dafür gibt es drei Wege – je nachdem, wer die Rolle vergibt und wie oft.

Aktualisiert am 27. Oktober 2026. Firexport, die Erweiterung in Methode 1, ist von uns. Die Methoden 2 und 3 brauchen sie nicht.

1. Mit Firexport Claims in der Firebase Console festlegen

Firexport ist eine kostenlose Chrome-Erweiterung, die dem ⋮-Menü jedes Nutzers unter Authentication > Nutzer (Users) den Eintrag Nutzer bearbeiten hinzufügt. Das Fenster zeigt die benutzerdefinierten Claims des Nutzers als Zeilen, die Sie hinzufügen, ändern und löschen können – neben seiner E-Mail, seinem Passwort, seinem Profil und seinen Anmeldeanbietern. Firexport speichert mit einem Google-Konto, das Sie verbinden – kein Dienstkontoschlüssel und kein Code einzurichten.

1. Installieren Sie Firexport aus dem Chrome Web Store.
2. Öffnen Sie in der Firebase Console Authentication > Nutzer (Users).
3. Fahren Sie mit der Maus über die Zeile des Nutzers, klicken Sie auf das ⋮ an ihrem rechten Ende und dann auf Nutzer bearbeiten.
4. Beim ersten Mal verlangt das Fenster, dass Sie Ihr Google-Konto verbinden: Klicken Sie auf Google-Konto verbinden, wählen Sie das Konto, das in der Console angemeldet ist, und erlauben Sie ihm im Fenster von Google, Nutzer in Firebase Authentication zu verwalten.
5. Klicken Sie unter Benutzerdefinierte Claims auf Claim hinzufügen, geben Sie seinen Namen ein, etwa admin, und wählen Sie einen Typ: string, number, boolean, object, array oder null. Objekte und Arrays enthalten ihrerseits weitere Zeilen.
6. Klicken Sie auf Speichern. Gespeichert wird nur, was Sie geändert haben; die übrigen Claims des Nutzers bleiben, wie sie waren.

Was das Fenster prüft

• Größe. Firebase nimmt höchstens 1.000 Byte an Claims pro Nutzer an. Das Fenster zählt die Bytes, während Sie tippen, und speichert nicht über die Grenze hinaus.
• Reservierte Namen. Ein Claim auf oberster Ebene darf keinen Namen tragen, den Firebase für seine eigenen Token-Felder reserviert, etwa sub, aud, exp oder firebase. Das Fenster markiert einen solchen Namen, bevor Sie speichern.
• Änderungen durch andere. Hat sich der Nutzer geändert, nachdem Sie das Fenster geöffnet haben, wird nichts gespeichert, und Sie können die aktuellen Werte lesen und es erneut versuchen.

Um die Claims eines Nutzers anzusehen, ohne etwas zu ändern, klicken Sie auf das Info-Symbol am Anfang der Zeilenaktionen: Seine Karte listet den ganzen Datensatz des Nutzers auf, benutzerdefinierte Claims eingeschlossen. Soll ein Nutzer, den es noch nicht gibt, gleich eine Rolle bekommen, finden Sie im ⋮-Menü des Buttons Nutzer hinzufügen den Eintrag Erweitert, der Claims zusammen mit den übrigen Angaben annimmt. Gespeichert wird mit den Berechtigungen des verbundenen Kontos; dazu muss die Berechtigung gehören, Nutzer in Firebase Authentication zu verwalten. Die Daten Ihrer Nutzer gehen von Ihrem Browser direkt zu Google und nie zu uns. „Nutzer bearbeiten“ ist in jedem Tarif kostenlos.

Legen Sie benutzerdefinierte Firebase-Claims in der Console fest und prüfen Sie sie – ohne Skript und ohne Dienstkontoschlüssel.

Zu Chrome hinzufügen – kostenlos

2. Mit einem Admin-SDK-Skript Claims festlegen

Um vielen Nutzern denselben Claim zu geben oder ihn in einem Skript festzuhalten, das Sie erneut ausführen können, nutzen Sie das Firebase Admin SDK aus Node.js. Das Skript unten nimmt die Claims als JSON und beliebig viele UIDs oder E-Mail-Adressen entgegen und führt die Claims mit denen zusammen, die jeder Nutzer schon hat. Es braucht ein Konto, das Nutzer verwalten darf: einen Projekt-Inhaber oder -Bearbeiter oder die Rolle Firebase Authentication-Administrator.

1. SDK installieren: npm install firebase-admin
2. Für lokale Anmeldedaten anmelden: gcloud auth application-default login. Auf einem Server lassen Sie stattdessen GOOGLE_APPLICATION_CREDENTIALS auf einen Dienstkontoschlüssel zeigen.
3. Speichern Sie das Skript unten als set-claims.mjs, ersetzen Sie your-project-id und führen Sie node set-claims.mjs '{"admin":true}' maya@example.com aus.

// Usage: node set-claims.mjs '{"admin":true}' maya@example.com u2   → adds admin: true to each user's claims
// Users are UIDs or emails. The claims you pass are merged into the ones each user has; null removes one.
import { initializeApp } from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';

initializeApp({ projectId: 'your-project-id' });
const auth = getAuth();
const [json, ...users] = process.argv.slice(2);
if (!json || !users.length) throw new Error(`Usage: node set-claims.mjs '{"admin":true}' <uid or email> ...`);
const changes = JSON.parse(json);
if (typeof changes !== 'object' || changes === null || Array.isArray(changes)) throw new Error('Pass the claims as a JSON object');

for (const who of users) {
  const user = who.includes('@') ? await auth.getUserByEmail(who) : await auth.getUser(who);
  // setCustomUserClaims() replaces every claim the user has, so start from the current ones.
  const claims = { ...user.customClaims, ...changes };
  for (const [name, value] of Object.entries(claims)) if (value === null) delete claims[name];
  await auth.setCustomUserClaims(user.uid, claims);
  console.log(`${who}: ${JSON.stringify(claims)}`);
}

• setCustomUserClaims() ersetzt alle Claims eines Nutzers durch das, was Sie übergeben. Deshalb liest das Skript zuerst die aktuellen Claims: Ein Aufruf nur mit {"admin":true} würde die anderen löschen.
• Ein Wert null entfernt diesen Claim, {"admin":null} entzieht also die Rolle.
• Bei Claims über 1.000 Byte oder mit einem reservierten Namen wirft das Admin SDK einen Fehler, und der Nutzer behält die Claims, die er hatte.

3. Die Admins Ihrer App Claims per Cloud Function festlegen lassen

Gehören Rollen zu Ihrer App – etwa ein Admin-Bereich, in dem Moderatoren ernannt werden –, muss das Admin SDK auf einem Server laufen, den Sie kontrollieren. Der übliche Ort dafür ist eine aufrufbare Cloud Function. Die Funktion unten erlaubt einem Nutzer, dessen Token bereits admin: true enthält, Claims für einen anderen Nutzer festzulegen. Das Bereitstellen von Funktionen erfordert den Blaze-Tarif.

// functions/index.js: a callable function your app's admin screen calls as setClaims({ uid, claims })
const { onCall, HttpsError } = require('firebase-functions/v2/https');
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');

initializeApp();

exports.setClaims = onCall(async (request) => {
  // Only a user whose token already says admin: true may change claims. Give the first admin theirs another way.
  if (request.auth?.token.admin !== true) throw new HttpsError('permission-denied', 'Only admins can set claims');
  const { uid, claims } = request.data;
  const user = await getAuth().getUser(uid);
  const next = { ...user.customClaims, ...claims }; // setCustomUserClaims() replaces them all, so keep the others
  await getAuth().setCustomUserClaims(uid, next);
  return { uid, claims: next };
});

Stellen Sie sie mit firebase deploy --only functions bereit und rufen Sie sie dann aus der App auf:

import { getFunctions, httpsCallable } from 'firebase/functions';

await httpsCallable(getFunctions(), 'setClaims')({ uid: 'u1', claims: { editor: true } });

Irgendjemand muss der erste Admin sein. Geben Sie diesem einen Konto den Claim admin mit Methode 1 oder 2.

Wann neue Claims wirken und wie Sie sie nutzen

Claims stehen im ID-Token, das Firebase etwa einmal pro Stunde erneuert. Ein Nutzer sieht neue Claims bei der nächsten Erneuerung oder der nächsten Anmeldung. Um sie sofort zu bekommen, kann die App getIdToken(true) für den angemeldeten Nutzer aufrufen und sie dann mit getIdTokenResult() lesen. Sicherheitsregeln lesen sie aus request.auth.token:

match /posts/{postId} {
  allow read: if true;
  allow write: if request.auth != null && request.auth.token.admin == true;
}

• Claims sind für Zugriffsrechte gedacht, nicht für Profildaten. Sie gehen mit jeder Anfrage mit, und Firebase begrenzt sie auf 1.000 Byte.
• Der Nutzer kann seine eigenen Claims lesen, indem er sein Token decodiert. Speichern Sie darin also keine Geheimnisse.
• Um die Claims aller Nutzer in einer Datei zu haben, exportieren Sie die Nutzer. Die Anleitung Firebase-Auth-Nutzer exportieren zeigt drei Wege dafür.

FAQ

Kann man benutzerdefinierte Claims in der Firebase Console festlegen?

Nicht mit der Console allein. Authentication > Nutzer (Users) hat kein Feld für benutzerdefinierte Claims und zeigt sie nicht an. Festgelegt werden sie mit dem Admin SDK – aus einem Skript, auf einem Server oder in einer Cloud Function – oder mit einer Browser-Erweiterung wie Firexport, die dem Tab Nutzer (Users) den Eintrag „Nutzer bearbeiten“ hinzufügt.

Wie sehe ich die benutzerdefinierten Claims eines Nutzers?

Die Console zeigt sie nicht an. Mit dem Admin SDK liefert getUser(uid) sie als customClaims. In der App liefert getIdTokenResult() sie für den angemeldeten Nutzer als claims. Firexport zeigt sie auf der Info-Karte jeder Zeile unter Authentication > Nutzer (Users).

Warum sieht meine App die neuen benutzerdefinierten Claims nicht?

Claims werden aus dem ID-Token gelesen, und das aktuelle Token des Nutzers wurde ausgestellt, bevor Sie sie festgelegt haben. Firebase erneuert es innerhalb einer Stunde, und bei einer neuen Anmeldung gibt es ein neues. Um sie sofort zu übernehmen, rufen Sie getIdToken(true) für den angemeldeten Nutzer auf.

Ersetzt setCustomUserClaims die vorhandenen Claims?

Ja. Es setzt die Claims des Nutzers auf genau das Objekt, das Sie übergeben, sodass jeder Claim, der darin fehlt, entfernt wird. Lesen Sie die aktuellen Claims mit getUser() und führen Sie Ihre Änderung mit ihnen zusammen, wie es das Skript oben tut. Wenn Sie null übergeben, werden alle entfernt.

Wie groß dürfen benutzerdefinierte Claims in Firebase sein?

Höchstens 1.000 Byte für alle Claims eines Nutzers zusammen, als JSON. Namen der obersten Ebene, die Firebase für seine eigenen Token-Felder verwendet, sind reserviert: acr, amr, at_hash, aud, auth_time, azp, cnf, c_hash, exp, firebase, iat, iss, jti, nbf, nonce und sub.