Firexport / Guides

Comment définir des revendications personnalisées dans Firebase Authentication

Les revendications personnalisées (custom claims) sont des valeurs que vous associez à un utilisateur Firebase, comme admin: true, et qui sont transmises dans son jeton d’ID. C’est ainsi que la plupart des applications attribuent à un utilisateur un rôle que les règles de sécurité et un backend peuvent vérifier. La console Firebase ne permet pas de les définir, et ne les affiche même pas : Authentication > Utilisateurs (Users) n’a aucun champ pour les revendications. Elles se définissent avec le SDK Admin, et il existe trois façons de le faire, selon qui attribue le rôle et à quelle fréquence.

Mis à jour le 27 octobre 2026. Firexport, l’extension de la méthode 1, est la nôtre. Les méthodes 2 et 3 n’en ont pas besoin.

1. Définir des revendications dans la console Firebase avec Firexport

Firexport est une extension Chrome gratuite qui ajoute Modifier l’utilisateur au menu ⋮ de chaque utilisateur dans Authentication > Utilisateurs (Users). Sa fenêtre affiche les revendications personnalisées de l’utilisateur sous forme de lignes que vous pouvez ajouter, modifier et supprimer, à côté de son e-mail, de son mot de passe, de son profil et de ses fournisseurs de connexion. Elle enregistre avec un compte Google que vous connectez, donc il n’y a ni clé de compte de service ni code à configurer.

1. Installez Firexport depuis le Chrome Web Store.
2. Dans la console Firebase, ouvrez Authentication > Utilisateurs (Users).
3. Survolez la ligne de l’utilisateur, cliquez sur le ⋮ à son extrémité droite, puis sur Modifier l’utilisateur.
4. La première fois, la fenêtre vous demande de Connecter un compte Google : choisissez le compte avec lequel vous êtes connecté à la console et, dans la fenêtre de Google, autorisez-le à gérer les utilisateurs de Firebase Authentication.
5. Sous Revendications personnalisées, cliquez sur Ajouter une revendication, saisissez son nom, par exemple admin, et choisissez un type : string, number, boolean, object, array ou null. Les objets et les tableaux contiennent eux-mêmes d’autres lignes.
6. Cliquez sur Enregistrer. Seul ce que vous avez modifié est enregistré, et les autres revendications de l’utilisateur restent telles quelles.

Ce que vérifie la fenêtre

• La taille. Firebase accepte au plus 1 000 octets de revendications par utilisateur. La fenêtre compte les octets au fil de la saisie et n’enregistre rien au-delà de la limite.
• Les noms réservés. Une revendication de premier niveau ne peut pas porter un nom que Firebase réserve à ses propres champs du jeton, comme sub, aud, exp ou firebase. La fenêtre signale un tel nom avant que vous n’enregistriez.
• Les modifications faites par quelqu’un d’autre. Si l’utilisateur a changé après l’ouverture de la fenêtre, rien n’est enregistré, et vous pouvez lire les dernières valeurs et réessayer.

Pour voir les revendications d’un utilisateur sans rien modifier, cliquez sur l’icône d’information, au début des actions de la ligne : sa fiche présente l’enregistrement complet de l’utilisateur, revendications personnalisées comprises. Pour attribuer un rôle à un utilisateur qui n’existe pas encore, le menu ⋮ du bouton Ajouter un utilisateur propose Avancé, qui accepte les revendications en même temps que le reste. Les enregistrements utilisent les autorisations du compte connecté, qui doivent permettre de gérer les utilisateurs de Firebase Authentication. Les données de vos utilisateurs vont de votre navigateur directement chez Google, et jamais chez nous. La fonction Modifier l’utilisateur est gratuite dans toutes les formules.

Définissez et vérifiez les revendications personnalisées Firebase depuis la console, sans script ni clé de compte de service.

Ajouter à Chrome — gratuit

2. Définir des revendications avec un script Admin SDK

Pour attribuer la même revendication à de nombreux utilisateurs, ou pour la garder dans un script que vous pouvez réexécuter, utilisez le SDK Admin Firebase depuis Node.js. Le script ci-dessous prend les revendications en JSON et autant d’UID ou d’e-mails que vous voulez, et fusionne les revendications avec celles que chaque utilisateur possède déjà. Il lui faut un compte qui peut gérer les utilisateurs : un Propriétaire ou un Éditeur du projet, ou le rôle Administrateur Firebase Authentication.

1. Installez le SDK : npm install firebase-admin
2. Connectez-vous pour obtenir des identifiants locaux : gcloud auth application-default login. Sur un serveur, faites plutôt pointer GOOGLE_APPLICATION_CREDENTIALS vers une clé de compte de service.
3. Enregistrez le script ci-dessous sous set-claims.mjs, remplacez your-project-id et exécutez node set-claims.mjs '{"admin":true}' maya@example.com.

// 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() remplace toutes les revendications d’un utilisateur par ce que vous lui passez. C’est pourquoi le script lit d’abord les revendications actuelles : l’appeler avec seulement {"admin":true} supprimerait les autres.
• Une valeur null supprime cette revendication : {"admin":null} retire donc le rôle.
• Avec des revendications de plus de 1 000 octets, ou un nom réservé, le SDK Admin lève une erreur, et l’utilisateur concerné garde les revendications qu’il avait.

3. Laisser les administrateurs de votre application définir des revendications avec une Cloud Function

Quand les rôles font partie de votre application, par exemple un écran d’administration où l’on nomme des modérateurs, le SDK Admin doit s’exécuter sur un serveur que vous contrôlez. Une Cloud Function appelable est l’endroit habituel. Celle ci-dessous permet à un utilisateur dont le jeton indique déjà admin: true de définir les revendications d’un autre utilisateur. Le déploiement de fonctions exige la formule Blaze.

// 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 };
});

Déployez-la avec firebase deploy --only functions, puis appelez-la depuis l’application :

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

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

Il faut bien un premier administrateur. Donnez à ce compte sa revendication admin avec la méthode 1 ou 2.

Quand les nouvelles revendications prennent effet, et comment les utiliser

Les revendications se trouvent dans le jeton d’ID, que Firebase renouvelle environ une fois par heure. Un utilisateur voit les nouvelles revendications au prochain renouvellement ou à sa prochaine connexion. Pour les obtenir tout de suite, l’application peut appeler getIdToken(true) sur l’utilisateur connecté, puis les lire avec getIdTokenResult(). Les règles de sécurité les lisent dans request.auth.token :

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

• Les revendications servent à contrôler l’accès, pas à stocker des données de profil. Elles accompagnent chaque requête, et Firebase les plafonne à 1 000 octets.
• L’utilisateur peut lire ses propres revendications en décodant son jeton : n’y mettez donc pas de secrets.
• Pour obtenir les revendications de tous les utilisateurs dans un seul fichier, exportez les utilisateurs. Le guide pour exporter les utilisateurs Firebase Auth présente trois méthodes.

FAQ

Peut-on définir des revendications personnalisées dans la console Firebase ?

Pas avec la console seule. Authentication > Utilisateurs (Users) n’a aucun champ pour les revendications personnalisées et ne les affiche pas. Elles se définissent avec le SDK Admin, depuis un script, un serveur ou une Cloud Function, ou avec une extension de navigateur comme Firexport, qui ajoute Modifier l’utilisateur à l’onglet Utilisateurs (Users).

Comment voir les revendications personnalisées d’un utilisateur ?

La console ne les affiche pas. Avec le SDK Admin, getUser(uid) les renvoie dans customClaims. Dans l’application, getIdTokenResult() les renvoie dans claims pour l’utilisateur connecté. Firexport les affiche dans la fiche d’information de chaque ligne d’Authentication > Utilisateurs (Users).

Pourquoi mon application ne voit-elle pas les nouvelles revendications personnalisées ?

Les revendications sont lues dans le jeton d’ID, et le jeton actuel de l’utilisateur a été émis avant que vous ne les définissiez. Firebase le renouvelle dans l’heure, et une nouvelle connexion en fournit un nouveau. Pour les prendre en compte immédiatement, appelez getIdToken(true) sur l’utilisateur connecté.

setCustomUserClaims remplace-t-il les revendications existantes ?

Oui. Il remplace les revendications de l’utilisateur par exactement l’objet que vous passez : toute revendication absente de cet objet est supprimée. Lisez les revendications actuelles avec getUser() et fusionnez-y votre modification, comme le fait le script ci-dessus. Passer null les supprime toutes.

Quelle taille peuvent atteindre les revendications personnalisées Firebase ?

Au plus 1 000 octets pour l’ensemble des revendications d’un utilisateur, en JSON. Les noms de premier niveau que Firebase utilise pour ses propres champs du jeton sont réservés : acr, amr, at_hash, aud, auth_time, azp, cnf, c_hash, exp, firebase, iat, iss, jti, nbf, nonce et sub.