Firexport / Guías

Cómo asignar reclamaciones personalizadas en Firebase Authentication

Las reclamaciones personalizadas (custom claims) son valores que adjuntas a un usuario de Firebase, como admin: true, y que viajan en su token de ID. Es así como la mayoría de las apps le dan a un usuario un rol que las reglas de seguridad y un backend pueden comprobar. Firebase console no puede asignarlas, y ni siquiera las muestra: Authentication > Usuarios (Users) no tiene ningún campo para reclamaciones. Se asignan con el Admin SDK, y hay tres formas de hacerlo, según quién otorgue el rol y con qué frecuencia.

Actualizado el 27 de octubre de 2026. Firexport, la extensión del método 1, es nuestra. Los métodos 2 y 3 no la necesitan.

1. Asignar reclamaciones en Firebase console con Firexport

Firexport es una extensión gratuita de Chrome que agrega Editar usuario al menú ⋮ de cada usuario en Authentication > Usuarios (Users). Su ventana muestra las reclamaciones personalizadas del usuario como filas que puedes agregar, cambiar y borrar, junto a su correo, contraseña, perfil y proveedores de acceso. Guarda con una cuenta de Google que tú conectas, así que no hay que configurar ninguna clave de cuenta de servicio ni código.

1. Instala Firexport desde Chrome Web Store.
2. En Firebase console, abre Authentication > Usuarios (Users).
3. Pasa el cursor sobre la fila del usuario, haz clic en el ⋮ que hay en su extremo derecho y luego en Editar usuario.
4. La primera vez, la ventana te pide Conectar cuenta de Google: elige la cuenta con la que accediste a la consola y, en la ventana de Google, permite que administre los usuarios de Firebase Authentication.
5. En Reclamaciones personalizadas, haz clic en Agregar reclamación, escribe su nombre, como admin, y elige un tipo: string, number, boolean, object, array o null. Los tipos object y array llevan más filas dentro.
6. Haz clic en Guardar. Solo se guarda lo que cambiaste, y las demás reclamaciones del usuario se quedan como estaban.

Qué comprueba la ventana

• Tamaño. Firebase admite como máximo 1.000 bytes de reclamaciones por usuario. La ventana cuenta los bytes mientras escribes y no guarda si se pasa del límite.
• Nombres reservados. Una reclamación de primer nivel no puede usar un nombre que Firebase reserva para sus propios campos del token, como sub, aud, exp o firebase. La ventana la marca antes de que guardes.
• Cambios de otra persona. Si el usuario cambió después de que abriste la ventana, no se guarda nada, y puedes leer los valores más recientes y volver a intentarlo.

Para ver las reclamaciones de un usuario sin cambiar nada, haz clic en el ícono de información al inicio de las acciones de la fila: su tarjeta muestra el registro completo del usuario, reclamaciones personalizadas incluidas. Para dar un rol a un usuario que todavía no existe, el menú ⋮ del botón Agregar usuario tiene Avanzado, que acepta reclamaciones junto con lo demás. Al guardar se usan los permisos de la cuenta conectada, que deben incluir la administración de usuarios de Firebase Authentication. Los datos de tus usuarios van de tu navegador directamente a Google, y nunca a nosotros. Editar usuario es gratis en todos los planes.

Asigna y revisa reclamaciones personalizadas de Firebase desde la consola, sin scripts ni claves de cuenta de servicio.

Añadir a Chrome — gratis

2. Asignar reclamaciones con un script del Admin SDK

Para dar la misma reclamación a muchos usuarios, o para tenerla en un script que puedas volver a ejecutar, usa el Firebase Admin SDK desde Node.js. El script de abajo recibe las reclamaciones en JSON y cualquier cantidad de UID o correos, y combina las reclamaciones con las que ya tiene cada usuario. Necesita una cuenta que pueda administrar usuarios: un Propietario o Editor del proyecto, o el rol Administrador de Firebase Authentication.

1. Instala el SDK: npm install firebase-admin
2. Inicia sesión para obtener credenciales locales: gcloud auth application-default login. En un servidor, apunta GOOGLE_APPLICATION_CREDENTIALS a una clave de cuenta de servicio en su lugar.
3. Guarda el script de abajo como set-claims.mjs, reemplaza your-project-id y ejecuta 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() reemplaza todas las reclamaciones de un usuario por lo que le pases. Por eso el script lee primero las reclamaciones actuales: llamarlo solo con {"admin":true} borraría las demás.
• Un valor null quita esa reclamación, así que {"admin":null} retira el rol.
• Con reclamaciones de más de 1.000 bytes, o con un nombre reservado, el Admin SDK lanza un error, y ese usuario conserva las reclamaciones que tenía.

3. Dejar que los administradores de tu app asignen reclamaciones con una Cloud Function

Cuando los roles forman parte de tu app, por ejemplo una pantalla de administración donde se nombran moderadores, el Admin SDK tiene que ejecutarse en un servidor que tú controlas. Lo habitual es una Cloud Function invocable. La de abajo permite que un usuario cuyo token ya dice admin: true asigne reclamaciones a otro usuario. Desplegar funciones requiere el plan 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 };
});

Despliégala con firebase deploy --only functions y luego llámala desde la app:

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

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

Alguien tiene que ser el primer administrador. Dale a esa cuenta su reclamación admin con el método 1 o el 2.

Cuándo surten efecto las nuevas reclamaciones y cómo usarlas

Las reclamaciones viven en el token de ID, que Firebase actualiza más o menos una vez por hora. Un usuario ve las nuevas reclamaciones en la siguiente actualización o en su siguiente inicio de sesión. Para obtenerlas de inmediato, la app puede llamar a getIdToken(true) en el usuario que inició sesión y luego leerlas con getIdTokenResult(). Las reglas de seguridad las leen de request.auth.token:

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

• Las reclamaciones son para el acceso, no para datos de perfil. Van en cada solicitud, y Firebase las limita a 1.000 bytes.
• El usuario puede leer sus propias reclamaciones decodificando su token, así que no guardes secretos en ellas.
• Para tener las reclamaciones de todos los usuarios en un solo archivo, exporta los usuarios. La guía para exportar usuarios de Firebase Auth muestra tres formas.

Preguntas frecuentes

¿Se pueden asignar reclamaciones personalizadas en Firebase console?

No solo con la consola. Authentication > Usuarios (Users) no tiene ningún campo para reclamaciones personalizadas y no las muestra. Se asignan con el Admin SDK, desde un script, un servidor o una Cloud Function, o con una extensión del navegador como Firexport, que agrega Editar usuario a la pestaña Usuarios (Users).

¿Cómo veo las reclamaciones personalizadas de un usuario?

La consola no las muestra. Con el Admin SDK, getUser(uid) las devuelve como customClaims. En la app, getIdTokenResult() las devuelve como claims para el usuario que inició sesión. Firexport las muestra en la tarjeta de información de cada fila en Authentication > Usuarios (Users).

¿Por qué mi app no ve las nuevas reclamaciones personalizadas?

Las reclamaciones se leen del token de ID, y el token actual del usuario se emitió antes de que las asignaras. Firebase lo actualiza en menos de una hora, y un nuevo inicio de sesión obtiene uno nuevo. Para recogerlas de inmediato, llama a getIdToken(true) en el usuario que inició sesión.

¿setCustomUserClaims reemplaza las reclamaciones existentes?

Sí. Establece como reclamaciones del usuario exactamente el objeto que le pases, así que se elimina cualquier reclamación que no esté en él. Lee las reclamaciones actuales con getUser() y combina tu cambio con ellas, como hace el script de arriba. Pasar null las elimina todas.

¿Qué tamaño pueden tener las reclamaciones personalizadas de Firebase?

Como máximo 1.000 bytes para todas las reclamaciones de un usuario juntas, en JSON. Los nombres de primer nivel que Firebase usa para sus propios campos del token están reservados: acr, amr, at_hash, aud, auth_time, azp, cnf, c_hash, exp, firebase, iat, iss, jti, nbf, nonce y sub.