Firexport / 가이드

Firebase Authentication에서 커스텀 클레임을 설정하는 방법

커스텀 클레임(custom claims)은 admin: true처럼 Firebase 사용자에게 붙이는 값으로, 사용자의 ID 토큰에 담겨 전달됩니다. 대부분의 앱은 커스텀 클레임으로 사용자에게 역할을 주며, 보안 규칙과 백엔드가 그 역할을 확인할 수 있습니다. Firebase 콘솔은 커스텀 클레임을 설정할 수 없을 뿐 아니라 보여 주지도 않습니다. Authentication > 사용자(Users)에는 클레임을 넣는 칸이 없습니다. 클레임은 Admin SDK로 설정하며, 역할을 누가, 얼마나 자주 주는지에 따라 방법이 세 가지 있습니다.

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,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 Function으로 앱 관리자가 클레임을 설정하게 하기

역할이 앱 기능의 일부일 때, 예를 들어 관리자 화면에서 운영자를 임명한다면, Admin SDK는 직접 운영하는 서버에서 실행해야 합니다. 보통은 호출 가능 Cloud Function을 씁니다. 아래 함수는 토큰에 이미 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이나 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바이트로 제한합니다.
• 사용자는 자기 토큰을 디코딩해 자기 클레임을 읽을 수 있으므로, 클레임에 비밀 정보를 넣지 마세요.
• 모든 사용자의 클레임을 파일 하나로 받으려면 사용자를 내보내세요. Firebase Auth 사용자 내보내기 가이드에 세 가지 방법이 나와 있습니다.

FAQ

Firebase 콘솔에서 커스텀 클레임을 설정할 수 있나요?

콘솔만으로는 안 됩니다. Authentication > 사용자(Users)에는 커스텀 클레임을 넣는 칸이 없고, 클레임을 보여 주지도 않습니다. 커스텀 클레임은 스크립트, 서버, Cloud Function에서 Admin SDK로 설정하거나, 사용자 탭에 사용자 수정을 추가하는 Firexport 같은 브라우저 확장 프로그램으로 설정합니다.

사용자의 커스텀 클레임은 어떻게 확인하나요?

콘솔에는 나오지 않습니다. Admin SDK에서는 getUser(uid)가 클레임을 customClaims로 돌려줍니다. 앱에서는 getIdTokenResult()가 로그인한 사용자의 클레임을 claims로 돌려줍니다. Firexport는 Authentication > 사용자(Users)에서 각 행의 정보 카드에 클레임을 보여 줍니다.

앱에 새 커스텀 클레임이 반영되지 않는 이유는 무엇인가요?

클레임은 ID 토큰에서 읽는데, 사용자의 현재 토큰은 클레임을 설정하기 전에 발급된 것입니다. Firebase는 1시간 안에 토큰을 갱신하고, 새로 로그인하면 새 토큰을 받습니다. 바로 반영하려면 로그인한 사용자에 대해 getIdToken(true)를 호출하세요.

setCustomUserClaims는 기존 클레임을 대체하나요?

네. 사용자의 클레임을 넘긴 객체와 정확히 같게 설정하므로, 그 객체에 없는 클레임은 삭제됩니다. 위의 스크립트처럼 getUser()로 현재 클레임을 읽은 뒤 바꿀 내용을 합치세요. null을 넘기면 클레임이 모두 삭제됩니다.

Firebase 커스텀 클레임의 크기 제한은 얼마인가요?

사용자 한 명의 모든 클레임을 합쳐 JSON으로 최대 1,000바이트입니다. Firebase가 자체 토큰 필드에 쓰는 최상위 이름은 예약되어 있습니다: acr, amr, at_hash, aud, auth_time, azp, cnf, c_hash, exp, firebase, iat, iss, jti, nbf, nonce, sub.