在 2024 年演示日活动中，观看有关如何使用 Firebase 构建和运行 AI 赋能应用的演示。立即观看。

서버에 Firebase Admin SDK 추가

Admin SDK는 권한이 있는 환경에서 Firebase와 상호작용하여 다음과 같은 작업을 수행할 수 있는 서버 라이브러리 집합입니다.

전체 관리자 권한으로 일괄 데이터 관리 및 기타 작업을 위해 Firebase Data Connect 서비스에서 쿼리 및 변형을 실행합니다.
전체 관리자 권한으로 Realtime Database 데이터를 읽고 씁니다.
Firebase Cloud Messaging 서버 프로토콜에 대한 간단한 대안적인 접근법을 사용하여 프로그래매틱 방식으로 Firebase Cloud Messaging 메시지를 전송합니다.
Firebase 인증 토큰을 생성하고 검증합니다.
Cloud Storage 버킷과 같은 Google Cloud 리소스 및 Firebase 프로젝트에 연결된 Cloud Firestore 데이터베이스에 액세스합니다.
간소화된 관리 콘솔을 직접 만들어 인증을 위해 사용자 데이터를 조회하거나 사용자의 이메일 주소를 변경하는 등의 작업을 수행합니다.

서버와 같은 관리자 권한 환경에서의 액세스가 아니라 최종 사용자의 액세스를 위한 클라이언트로 Node.js SDK를 사용하려는 경우(예: Node.js 데스크톱 또는 IoT 애플리케이션) 클라이언트 자바스크립트 SDK 설정 안내를 따라야 합니다.

다음은 각 언어에서 지원되는 Firebase 기능을 보여주는 표입니다.

기능	Node.js	자바	Python	Go	C#
커스텀 토큰 발급
ID 토큰 확인
사용자 관리
커스텀 클레임으로 액세스 제어
갱신 토큰 해지
사용자 가져오기
세션 쿠키 관리
이메일 작업 링크 생성
SAML/OIDC 제공업체 구성 관리
멀티테넌시 지원
Firebase Data Connect
Realtime Database				*
Firebase Cloud Messaging
FCM 멀티캐스트
FCM 주제 구독 관리
Cloud Storage
Cloud Firestore
Cloud Tasks로 큐에 함수 추가
프로젝트 관리
보안 규칙
ML 모델 관리
Firebase Remote Config
Firebase App Check
Firebase Extensions

이러한 용도의 Admin SDK 통합에 대한 자세한 내용은 해당 Realtime Database, FCM, Authentication Remote Config, Cloud Storage 문서를 참조하세요. 이 페이지의 나머지 부분에서는 기본적인 Admin SDK 설정 방법을 보여줍니다.

기본 요건

서버 앱이 있는지 확인합니다.
사용하는 Admin SDK에 따라 서버에서 다음을 실행해야 합니다.
- Admin Node.js SDK — Node.js 18 이상
- Admin 자바 SDK — 자바 8 이상
- Admin Python SDK — Python 3.7 이상(Python 3.8 이상 권장)
  Python 3.7은 지원 중단되었습니다.
- Admin Go SDK — Go 1.21 이상
- Admin .NET SDK — .NET Framework 4.6.2 이상 또는 .NET Standard 2.0(.NET 6.0 이상용)

Firebase 프로젝트 및 서비스 계정 설정

Firebase Admin SDK를 사용하려면 다음이 필요합니다.

Firebase 프로젝트
Firebase와 통신할 Firebase Admin SDK 서비스 계정. 이 서비스 계정은 Firebase 프로젝트를 만들거나 Google Cloud 프로젝트에 Firebase를 추가할 때 자동으로 생성됩니다.
서비스 계정의 사용자 인증 정보가 포함된 구성 파일

아직 Firebase 프로젝트가 없으면 Firebase Console에서 프로젝트를 만들어야 합니다. Firebase 프로젝트에 대한 자세한 내용은 Firebase 프로젝트 이해를 참조하세요.

Firebase 프로젝트 만들기

Firebase Console에서 프로젝트 추가를 클릭합니다.
- 기존 Google Cloud 프로젝트에 Firebase 리소스를 추가하려면 프로젝트 이름을 입력하거나 드롭다운 메뉴에서 선택합니다.
- 새 프로젝트를 만들려면 원하는 프로젝트 이름을 입력합니다. 필요한 경우 프로젝트 이름 아래에 표시되는 프로젝트 ID를 수정할 수도 있습니다.
  
  Firebase는 지정된 이름을 토대로 Firebase 프로젝트의 고유 ID를 생성합니다. Firebase에서 프로젝트의 리소스를 프로비저닝한 후에는 프로젝트 ID를 수정할 수 없으므로 이 프로젝트 ID를 수정하려면 지금 수정해야 합니다. Firebase에서 프로젝트 ID가 어떻게 사용되는지를 알아보려면 Firebase 프로젝트 이해를 참조하세요.
메시지가 표시되면 Firebase 약관을 검토하고 이에 동의합니다.
계속을 클릭합니다.

(선택사항) 다음 Firebase 제품의 사용 환경을 최적화하려면 프로젝트에 Google Analytics를 설정합니다.

기존 Google Analytics 계정을 선택하거나 새 계정을 만듭니다.

새 계정을 만드는 경우 Analytics 보고 위치를 선택한 후 프로젝트의 데이터 공유 설정 및 Google Analytics 약관에 동의합니다.

프로젝트 만들기를 클릭합니다. 기존 Google Cloud 프로젝트를 사용하는 경우에는 Firebase 추가를 클릭합니다.

Firebase에서 Firebase 프로젝트용 리소스를 자동으로 프로비저닝합니다. 프로세스가 완료되면 Firebase Console에서 Firebase 프로젝트의 개요 페이지로 이동됩니다.

SDK 추가

새 프로젝트를 설정할 때는 원하는 언어의 SDK를 설치해야 합니다.

Node.js

Firebase Admin Node.js SDK는 npm으로 제공됩니다. 아직 package.json 파일이 없으면 npm init으로 파일을 만듭니다. 그런 다음 firebase-admin npm 패키지를 설치하고 package.json에 저장합니다.

npm install firebase-admin --save

애플리케이션에서 모듈을 사용하려면 자바스크립트 파일에서 require로 가져옵니다.

const { initializeApp } = require('firebase-admin/app');

ES2015를 사용하는 경우 import로 모듈을 가져올 수 있습니다.

import { initializeApp } from 'firebase-admin/app';

자바

Firebase Admin 자바 SDK는 Maven Central Repository에 게시되어 있습니다. 라이브러리를 설치하려면 build.gradle 파일에서 종속 항목으로 선언합니다.

dependencies {
  implementation 'com.google.firebase:firebase-admin:9.4.2'
}

Maven을 사용하여 애플리케이션을 빌드하는 경우 pom.xml에 다음과 같은 종속 항목을 추가할 수 있습니다.

<dependency>
  <groupId>com.google.firebase</groupId>
  <artifactId>firebase-admin</artifactId>
  <version>9.4.2</version>
</dependency>

Python

Firebase Admin Python SDK는 pip를 통해 제공됩니다. sudo를 통해 모든 사용자용으로 라이브러리를 설치할 수 있습니다.

sudo pip install firebase-admin

또는 --user 플래그를 전달하여 현재 사용자용으로만 라이브러리를 설치할 수 있습니다.

pip install --user firebase-admin

Go

Go Admin SDK는 go get 유틸리티를 사용하여 설치할 수 있습니다.

# Install the latest version:
go get firebase.google.com/go/v4@latest

# Or install a specific version:
go get firebase.google.com/go/v4@4.15.1

C#

.NET Admin SDK는 .NET 패키지 관리자를 사용하여 설치할 수 있습니다.

Install-Package FirebaseAdmin -Version 3.1.0

또는 dotnet 명령줄 유틸리티를 사용하여 설치합니다.

dotnet add package FirebaseAdmin --version 3.1.0

또는 .csproj 파일에 다음 패키지 참조 항목을 추가하여 설치할 수 있습니다.

<ItemGroup>
  <PackageReference Include="FirebaseAdmin" Version="3.1.0" />
</ItemGroup>

SDK 초기화

Firebase 프로젝트를 만든 후에 Google 애플리케이션 기본 사용자 인증 정보를 사용하여 SDK를 초기화할 수 있습니다. Google 환경에서는 기본 사용자 인증 정보 조회가 완전 자동화되어 환경 변수나 기타 구성을 제공할 필요가 없으므로 Cloud Run, App Engine, Cloud Functions 등의 Google 환경에서 실행되는 애플리케이션의 경우 이 방법으로 SDK를 초기화하는 것이 좋습니다.

필요에 따라 Realtime Database, Cloud Storage 또는 Cloud Functions와 같은 서비스의 초기화 옵션을 지정하려면 FIREBASE_CONFIG 환경 변수를 사용하세요. FIREBASE_CONFIG 변수의 내용이 {로 시작되면 JSON 객체로 파싱됩니다. 그렇지 않은 경우 SDK는 문자열이 옵션을 포함하는 JSON 파일의 경로라고 가정합니다.

Node.js

const app = initializeApp();

자바

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}init.go

C#

FirebaseApp.Create();

초기화되면 Admin SDK를 사용하여 다음 유형의 작업을 수행할 수 있습니다.

OAuth 2.0 갱신 토큰 사용

Admin SDK는 Google OAuth2 갱신 토큰으로 인증할 수 있는 사용자 인증 정보도 제공합니다.

Node.js

const myRefreshToken = '...'; // Get refresh token from OAuth2 flow

initializeApp({
  credential: refreshToken(myRefreshToken),
  databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

자바

FileInputStream refreshToken = new FileInputStream("path/to/refreshToken.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(refreshToken))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)

Go

opt := option.WithCredentialsFile("path/to/refreshToken.json")
config := &firebase.Config{ProjectID: "my-project-id"}
app, err := firebase.NewApp(context.Background(), config, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}init.go

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/refreshToken.json"),
});

Google 이외의 환경에서 SDK 초기화

기본 사용자 인증 정보 조회를 완전히 자동화할 수 없는 Google 이외의 서버 환경에서 작업하는 경우에는 내보낸 서비스 계정 키 파일로 SDK를 초기화하면 됩니다.

Firebase 프로젝트는 앱 서버 또는 신뢰할 수 있는 환경에서 Firebase 서버 API를 호출하는 데 사용할 수 있는 Google 서비스 계정을 지원합니다. 로컬에서 코드를 개발하거나 온프레미스에 애플리케이션을 배포하는 경우 이 서비스 계정을 통해 가져온 사용자 인증 정보를 사용하여 서버 요청을 승인할 수 있습니다.

서비스 계정을 인증하고 Firebase 서비스에 액세스하도록 승인하려면 JSON 형식의 비공개 키 파일을 생성해야 합니다.

서비스 계정의 비공개 키 파일을 생성하려면 다음 안내를 따르세요.

Firebase Console에서 설정 > 서비스 계정을 엽니다.
새 비공개 키 생성을 클릭한 다음 키 생성을 클릭하여 확인합니다.
키가 들어 있는 JSON 파일을 안전하게 저장합니다.

서비스 계정을 통한 승인 시 다음과 같은 2가지 방법을 사용하여 애플리케이션에 사용자 인증 정보를 제공할 수 있습니다. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하거나 코드에서 서비스 계정 키 경로를 명시적으로 전달하는 것입니다. 그러나 보안을 위해 첫 번째 방법을 강력하게 권장합니다.

환경 변수를 설정하는 방법은 다음과 같습니다.

GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키가 포함된 JSON 파일의 파일 경로로 설정합니다. 이 변수는 현재 셸 세션에만 적용되므로 새 세션을 열면 변수를 다시 설정합니다.

Linux 또는 macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

위 단계를 완료하면 애플리케이션 기본 사용자 인증 정보(ADC)에서 암묵적으로 사용자 인증 정보를 확인할 수 있으므로 Google 이외의 환경에서 테스트 또는 실행할 때 서비스 계정 사용자 인증 정보를 사용할 수 있습니다.

다음과 같이 SDK를 초기화합니다.

Node.js

initializeApp({
    credential: applicationDefault(),
    databaseURL: 'https://<DATABASE_NAME>.firebaseio.com'
});

자바

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}init.go

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "my-project-id",
});
FirebaseAppSnippets.cs

여러 앱 초기화

대부분의 경우에는 기본 앱 하나만 초기화하면 됩니다. 이 앱을 통해 아래와 같이 서로 대응하는 두 가지 방법으로 서비스에 액세스할 수 있습니다.

Node.js

// Initialize the default app
const defaultApp = initializeApp(defaultAppConfig);

console.log(defaultApp.name);  // '[DEFAULT]'

// Retrieve services via the defaultApp variable...
let defaultAuth = getAuth(defaultApp);
let defaultDatabase = getDatabase(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = getAuth();
defaultDatabase = getDatabase();

자바

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

System.out.println(defaultApp.getName());  // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
FirebaseAuth defaultAuth = FirebaseAuth.getInstance(defaultApp);
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.getInstance();
defaultDatabase = FirebaseDatabase.getInstance();

Python

# Import the Firebase service
from firebase_admin import auth

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)
print(default_app.name)  # "[DEFAULT]"

# Retrieve services via the auth package...
# auth.create_custom_token(...)

Go

// Initialize default app
app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access auth service from the default app
client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}init.go

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});
Console.WriteLine(defaultApp.Name); // "[DEFAULT]"

// Retrieve services by passing the defaultApp variable...
var defaultAuth = FirebaseAuth.GetAuth(defaultApp);

// ... or use the equivalent shorthand notation
defaultAuth = FirebaseAuth.DefaultInstance;

사용 사례에 따라서는 여러 앱을 동시에 만들어야 할 수 있습니다. 예를 들어 한 Firebase 프로젝트의 Realtime Database에서 데이터를 읽고 다른 프로젝트에는 커스텀 토큰을 발급해야 할 수 있습니다. 또는 두 앱을 서로 다른 사용자 인증 정보로 인증해야 할 수 있습니다. Firebase SDK로 각각 고유한 구성 정보를 사용하여 여러 앱을 동시에 만들 수 있습니다.

Node.js

// Initialize the default app
initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = initializeApp(otherAppConfig, 'other');

console.log(getApp().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
const defaultAuth = getAuth();
const defaultDatabase = getDatabase();

// Use the otherApp variable to retrieve the other app's services
const otherAuth = getAuth(otherApp);
const otherDatabase = getDatabase(otherApp);

자바

// Initialize the default app
FirebaseApp defaultApp = FirebaseApp.initializeApp(defaultOptions);

// Initialize another app with a different config
FirebaseApp otherApp = FirebaseApp.initializeApp(otherAppConfig, "other");

System.out.println(defaultApp.getName());  // "[DEFAULT]"
System.out.println(otherApp.getName());    // "other"

// Use the shorthand notation to retrieve the default app's services
FirebaseAuth defaultAuth = FirebaseAuth.getInstance();
FirebaseDatabase defaultDatabase = FirebaseDatabase.getInstance();

// Use the otherApp variable to retrieve the other app's services
FirebaseAuth otherAuth = FirebaseAuth.getInstance(otherApp);
FirebaseDatabase otherDatabase = FirebaseDatabase.getInstance(otherApp);

Python

# Initialize the default app
default_app = firebase_admin.initialize_app(cred)

#  Initialize another app with a different config
other_app = firebase_admin.initialize_app(cred, name='other')

print(default_app.name)    # "[DEFAULT]"
print(other_app.name)      # "other"

# Retrieve default services via the auth package...
# auth.create_custom_token(...)

# Use the `app` argument to retrieve the other app's services
# auth.create_custom_token(..., app=other_app)

Go

// Initialize the default app
defaultApp, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Initialize another app with a different config
opt := option.WithCredentialsFile("service-account-other.json")
otherApp, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

// Access Auth service from default app
defaultClient, err := defaultApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

// Access auth service from other app
otherClient, err := otherApp.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}init.go

C#

// Initialize the default app
var defaultApp = FirebaseApp.Create(defaultOptions);

// Initialize another app with a different config
var otherApp = FirebaseApp.Create(otherAppConfig, "other");

Console.WriteLine(defaultApp.Name); // "[DEFAULT]"
Console.WriteLine(otherApp.Name); // "other"

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = FirebaseAuth.DefaultInstance;

// Use the otherApp variable to retrieve the other app's services
var otherAuth = FirebaseAuth.GetAuth(otherApp);

Realtime Database 및 Authentication의 범위 설정

Google Compute Engine VM과 Google 애플리케이션 기본 사용자 인증 정보를 Realtime Database 또는 Authentication에 사용하는 경우 액세스 범위를 올바르게 설정해야 합니다. Realtime Database 및 Authentication의 경우 userinfo.email 및 cloud-platform 또는 firebase.database로 끝나는 범위가 필요합니다. 기존 액세스 범위를 확인하고 변경하려면 gcloud를 사용하여 다음 명령어를 실행하세요.

gcloud

# Check the existing access scopes
gcloud compute instances describe [INSTANCE_NAME] --format json

# The above command returns the service account information. For example:
  "serviceAccounts": [
   {
    "email": "your.gserviceaccount.com",
    "scopes": [
     "https://www.googleapis.com/auth/cloud-platform",
     "https://www.googleapis.com/auth/userinfo.email"
     ]
    }
  ],

# Stop the VM, then run the following command, using the service account
# that gcloud returned when you checked the scopes.

gcloud compute instances set-service-account [INSTANCE_NAME] --service-account "your.gserviceaccount.com" --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"

gcloud 최종 사용자 인증 정보로 테스트

gcloud auth application-default login을 실행하여 가져온 Google 애플리케이션 기본 사용자 인증 정보로 Admin SDK를 로컬에서 테스트할 때 Firebase Authentication을 사용하려면 다음과 같은 이유로 추가 변경이 필요합니다.

Firebase Authentication에서는 gcloud OAuth 클라이언트 ID를 사용하여 생성된 gcloud 최종 사용자 인증 정보를 허용하지 않습니다.
Firebase Authentication을 사용하려면 이러한 유형의 최종 사용자 인증 정보 초기화 시 프로젝트 ID를 제공해야 합니다.

이 문제를 해결하려면 자체 OAuth 2.0 클라이언트 ID를 사용하여 gcloud에서 Google 애플리케이션 기본 사용자 인증 정보를 생성하면 됩니다. OAuth 클라이언트 ID는 데스크톱 앱 애플리케이션 유형이어야 합니다.

gcloud

gcloud auth application-default login --client-id-file=[/path/to/client/id/file]

앱 초기화 시 프로젝트 ID를 명시적으로 지정하거나 GOOGLE_CLOUD_PROJECT 환경 변수를 사용할 수 있습니다. 환경 변수 사용 시 코드 테스트를 위해 추가로 변경해야 할 사항이 없습니다.

프로젝트 ID를 명시적으로 지정하려면 다음 안내를 따르세요.

Node.js

import { initializeApp, applicationDefault } from 'firebase-admin/app';

initializeApp({
  credential: applicationDefault(),
  projectId: '<FIREBASE_PROJECT_ID>',
});

자바

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setProjectId("<FIREBASE_PROJECT_ID>")
    .build();

FirebaseApp.initializeApp(options);

Python

app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)

Go

config := &firebase.Config{ProjectID: "<FIREBASE_PROJECT_ID>"}
app, err := firebase.NewApp(context.Background(), config)
if err != nil {
        log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
    ProjectId = "<FIREBASE_PROJECT_ID>",
});

다음 단계

Firebase 알아보기:

샘플 Firebase 앱을 살펴봅니다.
GitHub에서 Node.js, 자바, Python의 오픈소스 코드를 살펴봅니다.
Admin SDK 개발자가 올린 Admin SDK 관련 블로그 게시물을 읽습니다. 예: 프록시 서버를 통해 Firestore 및 Firebase에 액세스

앱에 Firebase 기능 추가:

Cloud Functions로 서버리스 백엔드를 작성합니다.
Realtime Database에 정보를 저장하거나 Cloud Storage에 blob 데이터를 저장합니다.
Cloud Messaging으로 알림을 수신합니다.