Firexport / ガイド

Firebase Authentication でカスタム クレームを設定する方法

カスタム クレーム（custom claims）は、admin: true のように Firebase のユーザーに付ける値で、ユーザーの ID トークンに含まれて送られます。多くのアプリは、セキュリティ ルールやバックエンドで確認できるロールを、この仕組みでユーザーに与えています。Firebase コンソールではカスタム クレームを設定できず、表示さえされません。Authentication > ユーザー（Users）には、クレームの欄がありません。設定には Admin SDK を使います。その方法は 3 つあり、誰がロールを与えるのか、どれくらいの頻度なのかによって使い分けます。

2026年10月27日 更新。 方法 1 の拡張機能 Firexport は私たちのものです。方法 2 と 3 には不要です。

1. Firexport で Firebase コンソールからクレームを設定

Firexport は、Authentication > ユーザー（Users）で各ユーザーの ⋮ メニューにユーザーを編集を追加する無料の Chrome 拡張機能です。そのウィンドウには、メールアドレス、パスワード、プロフィール、ログイン プロバイダと並んで、ユーザーのカスタム クレームが行として表示され、追加・変更・削除できます。接続した Google アカウントで保存するので、サービス アカウント キーもコードの準備も不要です。

1. Chrome ウェブストアから Firexport をインストールします。
2. Firebase コンソールで Authentication > ユーザー（Users）を開きます。
3. ユーザーの行にカーソルを合わせ、右端の ⋮ をクリックして、ユーザーを編集を選びます。
4. 初回は、ウィンドウから Google アカウントを接続するよう求められます。コンソールにログインしているアカウントを選び、Google のウィンドウで Firebase Authentication のユーザーの管理を許可します。
5. カスタム クレームでクレームを追加をクリックし、admin のような名前を入力して、タイプを string、number、boolean、object、array、null から選びます。object と array の中には、さらに行を入れられます。
6. 保存をクリックします。変更した部分だけが保存され、ユーザーのほかのクレームはそのまま残ります。

ウィンドウが確認すること

• サイズ。Firebase が受け付けるクレームは、ユーザー 1 人あたり 1,000 バイトまでです。ウィンドウは入力に合わせてバイト数を数え、上限を超えると保存しません。
• 予約された名前。トップレベルのクレームには、sub、aud、exp、firebase のように、Firebase がトークン自身の項目のために予約している名前は使えません。そうした名前があると、保存する前にウィンドウが印を付けます。
• ほかの人による変更。ウィンドウを開いたあとでユーザーが変更されていた場合、何も保存されません。最新の値を読み込んで、もう一度試せます。

何も変えずにユーザーのクレームを見るには、行の操作の先頭にある情報アイコンをクリックします。開くカードにはユーザーのレコード全体が載っていて、カスタム クレームも含まれます。まだ存在しないユーザーにロールを与えるには、ユーザーを追加ボタンの ⋮ メニューにある詳細を使います。ほかの項目と一緒にクレームも指定できます。保存は接続したアカウントの権限で行われるため、そのアカウントには Firebase Authentication のユーザーを管理する権限が必要です。ユーザーのデータはブラウザから直接 Google に送られ、私たちには一切送られません。ユーザーの編集はどのプランでも無料です。

スクリプトもサービス アカウント キーもなしで、Firebase のカスタム クレームをコンソールから設定・確認しましょう。

Chrome に追加 — 無料

2. Admin SDK スクリプトでクレームを設定

多くのユーザーに同じクレームを与える場合や、何度でも実行できるスクリプトとして残しておきたい場合は、Node.js から Firebase Admin SDK を使います。下のスクリプトは、クレームを JSON で、UID かメールアドレスをいくつでも受け取り、各ユーザーがすでに持っているクレームにマージします。ユーザーを管理できるアカウントが必要です。プロジェクトのオーナーか編集者、または Firebase Authentication 管理者のロールです。

1. SDK をインストール: npm install firebase-admin
2. ローカルの認証情報でサインイン: gcloud auth application-default login。サーバーでは代わりに GOOGLE_APPLICATION_CREDENTIALS でサービス アカウント キーを指定します。
3. 下のスクリプトを set-claims.mjs として保存し、your-project-id を置き換えて、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() は、ユーザーのクレームを渡したものですべて置き換えます。スクリプトが最初に今のクレームを読み込むのはそのためです。{"admin":true} だけを渡して呼び出すと、ほかのクレームは削除されてしまいます。
• 値を null にするとそのクレームが削除されるので、{"admin":null} でロールを外せます。
• 1,000 バイトを超えるクレームや予約された名前のクレームでは Admin SDK がエラーを投げ、そのユーザーのクレームは元のまま残ります。

3. Cloud Functions でアプリの管理者がクレームを設定できるようにする

モデレーターを任命する管理画面のように、ロールがアプリの一部である場合、Admin SDK は自分が管理するサーバーで実行する必要があります。その場所としては、Cloud Functions の呼び出し可能関数が一般的です。下の関数では、トークンにすでに admin: true があるユーザーが、別のユーザーにクレームを設定できます。関数のデプロイには 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 };
});

firebase deploy --only functions でデプロイし、アプリから呼び出します:

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

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

誰かが最初の管理者にならなければなりません。その 1 つのアカウントには、方法 1 か 2 で admin クレームを付けてください。

新しいクレームが反映されるタイミングと使い方

クレームは ID トークンの中にあり、Firebase はこのトークンを約 1 時間ごとに更新します。ユーザーに新しいクレームが反映されるのは、次の更新か次のログインのときです。すぐに取得するには、アプリでログイン中のユーザーに対して getIdToken(true) を呼び出してから、getIdTokenResult() で読み取ります。セキュリティ ルールでは request.auth.token から読み取ります:

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

• クレームはアクセス制御のためのもので、プロフィールのデータを入れる場所ではありません。すべてのリクエストに付いて送られ、Firebase はサイズを 1,000 バイトまでに制限しています。
• ユーザーは自分のトークンをデコードすれば自分のクレームを読めるので、秘密の情報は入れないでください。
• 全ユーザーのクレームを 1 つのファイルにまとめるには、ユーザーをエクスポートします。Firebase Auth のユーザーをエクスポートするガイドで 3 つの方法を紹介しています。

FAQ

Firebase コンソールでカスタム クレームを設定できますか？

コンソールだけではできません。Authentication > ユーザー（Users）にはカスタム クレームの欄がなく、表示もされません。設定するには、スクリプト、サーバー、または Cloud Functions から Admin SDK を使うか、ユーザー（Users）タブに「ユーザーを編集」を追加する Firexport のようなブラウザ拡張機能を使います。

ユーザーのカスタム クレームはどう確認しますか？

コンソールには表示されません。Admin SDK では、getUser(uid) が customClaims として返します。アプリでは、getIdTokenResult() がログイン中のユーザーのクレームを claims として返します。Firexport では、Authentication > ユーザー（Users）の各行の情報カードに表示されます。

アプリに新しいカスタム クレームが反映されないのはなぜですか？

クレームは ID トークンから読み取られます。ユーザーの今のトークンは、クレームを設定する前に発行されたものです。Firebase は 1 時間以内にトークンを更新し、ログインし直すと新しいトークンが発行されます。すぐに反映させるには、ログイン中のユーザーに対して getIdToken(true) を呼び出します。

setCustomUserClaims は既存のクレームを置き換えますか？

はい。ユーザーのクレームを、渡したオブジェクトとまったく同じ内容にするので、そこに含まれないクレームは削除されます。上のスクリプトのように、getUser() で今のクレームを読み込み、変更をそこにマージしてください。null を渡すと、すべて削除されます。

Firebase のカスタム クレームは、どれくらいの大きさまで設定できますか？

1 人のユーザーのクレームすべてを合わせて、JSON で 1,000 バイトまでです。Firebase がトークン自身の項目に使う名前は、トップレベルでは予約されています: acr、amr、at_hash、aud、auth_time、azp、cnf、c_hash、exp、firebase、iat、iss、jti、nbf、nonce、sub。