Firexport / Guias

Como definir declarações personalizadas no Firebase Authentication

Declarações personalizadas (custom claims) são valores que você associa a um usuário do Firebase, como admin: true, e que viajam no token de ID dele. É com elas que a maioria dos apps dá a um usuário um papel que as regras de segurança e um back-end podem verificar. O Console do Firebase não consegue defini-las, e nem sequer as mostra: Authentication > Usuários (Users) não tem nenhum campo para declarações. Elas são definidas com o Admin SDK, e há três formas de fazer isso, dependendo de quem dá o papel e com que frequência.

Atualizado em 27 de outubro de 2026. O Firexport, a extensão do método 1, é nosso. Os métodos 2 e 3 não precisam dele.

1. Definir declarações no Console do Firebase com o Firexport

O Firexport é uma extensão gratuita do Chrome que adiciona Editar usuário ao menu ⋮ de cada usuário em Authentication > Usuários (Users). A janela dele mostra as declarações personalizadas do usuário como linhas que você pode adicionar, alterar e excluir, ao lado do e-mail, da senha, do perfil e dos provedores de login dele. Ele salva com uma conta do Google que você conecta, então não há chave de conta de serviço nem código para configurar.

1. Instale o Firexport pela Chrome Web Store.
2. No Console do Firebase, abra Authentication > Usuários (Users).
3. Passe o mouse sobre a linha do usuário, clique no ⋮ na ponta direita dela e depois em Editar usuário.
4. Na primeira vez, a janela pede que você clique em Conectar conta do Google: escolha a conta com que você entrou no console e, na janela do Google, permita o acesso para gerenciar os usuários do Firebase Authentication.
5. Em Declarações personalizadas, clique em Adicionar declaração, digite o nome dela, como admin, e escolha um tipo: string, number, boolean, object, array ou null. Os tipos object e array guardam mais linhas dentro deles.
6. Clique em Salvar. Só o que você alterou é salvo, e as outras declarações do usuário ficam como estavam.

O que a janela verifica

• Tamanho. O Firebase aceita no máximo 1.000 bytes de declarações por usuário. A janela conta os bytes enquanto você digita e não salva além do limite.
• Nomes reservados. Uma declaração de nível superior não pode usar um nome que o Firebase reserva para os próprios campos do token, como sub, aud, exp ou firebase. A janela sinaliza um nome assim antes de você salvar.
• Alterações feitas por outra pessoa. Se o usuário mudou depois que você abriu a janela, nada é salvo, e você pode ler os valores mais recentes e tentar de novo.

Para ver as declarações de um usuário sem alterar nada, clique no ícone de informações no início das ações da linha: o cartão que ele abre lista o registro completo do usuário, incluindo as declarações personalizadas. Para dar um papel a um usuário que ainda não existe, o menu ⋮ do botão Adicionar usuário tem Avançado, que aceita as declarações junto com o resto. Os salvamentos usam as permissões da conta conectada, que precisam incluir o gerenciamento de usuários do Firebase Authentication. Os dados dos seus usuários vão do seu navegador direto para o Google, e nunca para nós. A função Editar usuário é gratuita em todos os planos.

Defina e confira as declarações personalizadas do Firebase no console, sem script nem chave de conta de serviço.

Adicionar ao Chrome — grátis

2. Definir declarações com um script do Admin SDK

Para dar a mesma declaração a muitos usuários, ou para mantê-la em um script que você pode executar de novo, use o Firebase Admin SDK no Node.js. O script abaixo recebe as declarações em JSON e qualquer número de UIDs ou e-mails, e mescla as declarações com as que cada usuário já tem. Ele precisa de uma conta que possa gerenciar usuários: um Proprietário ou Editor do projeto, ou o papel Administrador do Firebase Authentication.

1. Instale o SDK: npm install firebase-admin
2. Faça login para obter credenciais locais: gcloud auth application-default login. Em um servidor, aponte GOOGLE_APPLICATION_CREDENTIALS para uma chave de conta de serviço.
3. Salve o script abaixo como set-claims.mjs, substitua your-project-id e execute 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() substitui todas as declarações de um usuário pelo que você passar. Por isso o script lê primeiro as declarações atuais: chamá-lo só com {"admin":true} excluiria as outras.
• Um valor null remove aquela declaração, então {"admin":null} retira o papel.
• Declarações com mais de 1.000 bytes, ou com um nome reservado, fazem o Admin SDK lançar um erro, e aquele usuário mantém as declarações que tinha.

3. Deixar os administradores do seu app definirem declarações com uma Cloud Function

Quando os papéis fazem parte do seu app, por exemplo em uma tela de administração em que se nomeiam moderadores, o Admin SDK precisa rodar em um servidor que você controla. Uma Cloud Function chamável é o lugar mais comum para isso. A função abaixo permite que um usuário cujo token já diz admin: true defina declarações em outro usuário. Implantar funções exige o plano 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 };
});

Implante-a com firebase deploy --only functions e depois chame-a pelo app:

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

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

Alguém precisa ser o primeiro administrador. Dê a essa única conta a declaração admin com o método 1 ou 2.

Quando as novas declarações passam a valer, e como usá-las

As declarações ficam no token de ID, que o Firebase atualiza mais ou menos uma vez por hora. Um usuário vê as novas declarações na próxima atualização ou no próximo login. Para obtê-las na hora, o app pode chamar getIdToken(true) no usuário conectado e depois lê-las com getIdTokenResult(). As regras de segurança as leem em request.auth.token:

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

• As declarações servem para controlar o acesso, não para guardar dados de perfil. Elas vão junto em cada solicitação, e o Firebase as limita a 1.000 bytes.
• O usuário pode ler as próprias declarações decodificando o token dele, então não coloque segredos nelas.
• Para ter as declarações de todos os usuários em um único arquivo, exporte os usuários. O guia para exportar usuários do Firebase Auth mostra três formas.

Perguntas frequentes

É possível definir declarações personalizadas no Console do Firebase?

Não só com o console. Authentication > Usuários (Users) não tem campo para declarações personalizadas e não as mostra. Elas são definidas com o Admin SDK, a partir de um script, de um servidor ou de uma Cloud Function, ou com uma extensão do navegador como o Firexport, que adiciona Editar usuário à guia Usuários (Users).

Como vejo as declarações personalizadas de um usuário?

O console não as mostra. Com o Admin SDK, getUser(uid) as retorna como customClaims. No app, getIdTokenResult() as retorna como claims para o usuário conectado. O Firexport as mostra no cartão de informações de cada linha em Authentication > Usuários (Users).

Por que meu app não vê as novas declarações personalizadas?

As declarações são lidas do token de ID, e o token atual do usuário foi emitido antes de você defini-las. O Firebase o atualiza em até uma hora, e um novo login gera um token novo. Para obtê-las na hora, chame getIdToken(true) no usuário conectado.

O setCustomUserClaims substitui as declarações existentes?

Sim. Ele define as declarações do usuário exatamente como o objeto que você passa, então qualquer declaração que não esteja nele é removida. Leia as declarações atuais com getUser() e mescle sua alteração nelas, como faz o script acima. Passar null remove todas elas.

Qual pode ser o tamanho das declarações personalizadas do Firebase?

No máximo 1.000 bytes para todas as declarações de um usuário juntas, em JSON. Os nomes de nível superior que o Firebase usa para os próprios campos do token são reservados: acr, amr, at_hash, aud, auth_time, azp, cnf, c_hash, exp, firebase, iat, iss, jti, nbf, nonce e sub.