Menambahkan Firebase Admin SDK ke server

Admin SDK adalah serangkaian library server yang dapat Anda gunakan untuk berinteraksi dengan Firebase dari lingkungan istimewa untuk melakukan berbagai tindakan, antara lain:

• Membaca dan menulis data Realtime Database dengan hak istimewa admin penuh.
• Mengirim pesan Firebase Cloud Messaging secara terprogram menggunakan pendekatan alternatif yang sederhana terhadap protokol server Firebase Cloud Messaging.
• Membuat dan memverifikasi token autentikasi Firebase.
• Mengakses resource Google Cloud, seperti bucket Cloud Storage dan database Cloud Firestore, yang terkait dengan project Firebase Anda.
• Membuat konsol admin sederhana untuk melakukan hal-hal seperti mencari data pengguna atau mengubah alamat email pengguna untuk autentikasi.

Jika Anda tertarik untuk menggunakan Node.js SDK sebagai klien untuk akses pengguna akhir (misalnya, di aplikasi desktop Node.js atau IoT), bukan untuk akses admin dari lingkungan istimewa (seperti server), ikuti petunjuk untuk menyiapkan JavaScript SDK klien.

Berikut adalah matriks fitur yang menunjukkan fitur Firebase yang didukung dalam setiap bahasa:

Fitur	Node.js	Java	Python	Go	C#
Pembuatan Token Kustom
Verifikasi Token ID
Pengelolaan Pengguna
Mengontrol Akses dengan Klaim Kustom
Pencabutan Token Refresh
Mengimpor Pengguna
Pengelolaan Cookie Sesi
Membuat Link Tindakan Email
Mengelola konfigurasi penyedia SAML/OIDC
Dukungan multi-tenancy
Realtime Database				*
Firebase Cloud Messaging
FCM Multicast
Mengelola Langganan Topik FCM
Cloud Storage
Cloud Firestore
Pengelolaan Project
Aturan Keamanan
Pengelolaan Model ML
Firebase Remote Config
Firebase App Check

Catatan: Realtime Database API di Go Admin SDK saat ini tidak mendukung pemroses peristiwa realtime. Artinya, tidak ada ketentuan untuk menambahkan pemroses peristiwa ke referensi database agar dapat menerima notifikasi pembaruan realtime secara otomatis. Sebagai gantinya, dalam Go, pembaruan harus diambil secara proaktif dengan memanggil operasi baca secara eksplisit.

Untuk mempelajari integrasi Admin SDK lebih lanjut untuk penggunaan ini, baca dokumentasi Realtime Database, FCM, Authentication, Remote Config, dan Cloud Storage yang sesuai. Bagian selanjutnya dari halaman ini berfokus pada penyiapan dasar untuk Admin SDK.

Prasyarat

• Pastikan Anda memiliki aplikasi server.

• Pastikan server Anda menjalankan hal-hal berikut, sesuai dengan Admin SDK yang Anda gunakan:

  • Admin Node.js SDK — Node.js 12+
  • Admin Java SDK — Java 7+ (Java 8+ direkomendasikan)
    Dukungan Java 7 tidak digunakan lagi.
  • Admin Python SDK — Python 3.6+
  • Admin Go SDK — Go 1.11+
  • Admin .NET SDK — .NET Framework 4.5+ atau .Net Core 1.5+

Menyiapkan project Firebase dan akun layanan

Untuk menggunakan Firebase Admin SDK, Anda memerlukan hal-hal berikut:

• Project Firebase.
• Akun layanan Firebase Admin SDK untuk berkomunikasi dengan Firebase. Akun layanan ini dibuat secara otomatis saat Anda membuat project Firebase atau menambahkan Firebase ke project Google Cloud.
• File konfigurasi dengan kredensial akun layanan Anda.

Jika belum memiliki project Firebase, Anda harus membuatnya di Firebase console. Buka bagian Memahami Project Firebase untuk mempelajari project Firebase lebih lanjut.

Membuat project Firebase

1. Di Firebase console, klik Add project.

   • Untuk menambahkan resource Firebase ke project Google Cloud yang sudah ada, masukkan nama project-nya atau pilih dari menu dropdown.

   • Untuk membuat project baru, masukkan nama project yang diinginkan. Jika diinginkan, Anda juga dapat mengedit project ID yang ditampilkan di bawah nama project.

     Firebase menghasilkan ID unik untuk project Firebase Anda berdasarkan nama yang Anda berikan. Jika ingin mengedit project ID ini, Anda harus melakukannya sekarang karena project ID tidak dapat diubah setelah Firebase menyediakan resource untuk project Anda. Buka Memahami Project Firebase untuk mempelajari cara Firebase menggunakan project ID.

2. Jika diminta, tinjau dan setujui persyaratan Firebase.

3. Klik Continue.

4. (Opsional) Siapkan Google Analytics untuk project Anda untuk mengoptimalkan penggunaan produk-produk Firebase berikut:

   Firebase Crashlytics Firebase Predictions

   Firebase Cloud Messaging Firebase In-App Messaging

   Firebase Remote Config Firebase A/B Testing

   Pilih akun Google Analytics yang ada atau buat akun baru.

   Jika Anda membuat akun baru, pilih lokasi pelaporan Analytics, lalu setujui setelan berbagi data dan persyaratan Google Analytics untuk project Anda.

   Anda dapat sewaktu-waktu menyiapkan Google Analytics dari tab Integrations di Project settings.

5. Klik Create project (atau Add Firebase, jika Anda menggunakan project Google Cloud yang sudah ada).

Firebase otomatis menyediakan resource untuk project Firebase Anda. Begitu selesai, Anda akan dibawa ke halaman ringkasan untuk project Firebase Anda di Firebase console.

Menambahkan SDK

Jika menyiapkan project baru, Anda harus menginstal SDK untuk bahasa yang Anda pilih.

Node.js

Firebase Admin Node.js SDK tersedia di npm. Jika belum memiliki file package.json, buat file tersebut melalui npm init. Selanjutnya, instal paket npm firebase-admin dan simpan ke package.json Anda:

$ npm install firebase-admin --save

Untuk menggunakan modul tersebut di aplikasi Anda, terapkan require padanya dari file JavaScript apa pun:

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

Jika Anda menggunakan ES2015, Anda dapat menerapkan import pada modul tersebut:

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

Java

Firebase Admin Java SDK dipublikasikan ke repositori pusat Maven. Untuk menginstal library tersebut, deklarasikan sebagai dependensi di file build.gradle Anda:

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

Jika menggunakan Maven untuk mem-build aplikasi, Anda dapat menambahkan dependensi berikut ke pom.xml:

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

Python

Firebase Admin Python SDK tersedia melalui pip. Anda dapat menginstal library tersebut untuk semua pengguna melalui sudo:

$ sudo pip install firebase-admin

Atau, Anda dapat menginstal library hanya untuk pengguna saat ini dengan meneruskan flag --user:

$ pip install --user firebase-admin

Go

Go Admin SDK dapat diinstal menggunakan aplikasi utilitas go get:

# Install as a module dependency
$ go get firebase.google.com/go/v4

# Install to $GOPATH
$ go get firebase.google.com/go

C#

.NET Admin SDK dapat diinstal menggunakan pengelola paket .NET:

$ Install-Package FirebaseAdmin -Version 2.2.0

Sebagai alternatif, Anda dapat menginstalnya menggunakan aplikasi utilitas command line dotnet:

$ dotnet add package FirebaseAdmin --version 2.2.0

Atau, Anda dapat menginstalnya dengan menambahkan entri referensi paket berikut ke file .csproj Anda:

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

Menginisialisasi SDK

Setelah membuat project Firebase, Anda dapat menginisialisasi SDK dengan strategi otorisasi yang menggabungkan file akun layanan Anda dengan Kredensial Default Aplikasi Google.

Project Firebase mendukung akun layanan Google, yang dapat Anda gunakan untuk memanggil API server Firebase dari server aplikasi atau lingkungan tepercaya. Jika Anda mengembangkan kode secara lokal atau men-deploy aplikasi secara lokal, gunakan kredensial yang diperoleh melalui akun layanan ini untuk mengizinkan permintaan server.

Untuk mengautentikasi akun layanan dan memberinya akses ke layanan Firebase, Anda harus membuat file kunci pribadi dalam format JSON.

Untuk membuat file kunci pribadi bagi akun layanan Anda:

1. Di Firebase console, buka Settings > Service Accounts.

2. Klik Generate New Private Key, lalu konfirmasikan dengan mengklik Generate Key.

3. Simpan dengan aman file JSON yang memuat kunci tersebut.

Saat Anda memberi otorisasi melalui akun layanan, ada dua opsi untuk menyediakan kredensial ke aplikasi. Anda dapat menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, atau secara eksplisit meneruskan jalur ke kunci akun layanan dalam kode. Opsi pertama lebih aman dan sangat direkomendasikan.

Untuk menetapkan variabel lingkungan:

Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kunci akun layanan Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini. Jadi, jika Anda membuka sesi baru, tetapkan variabel kembali.

Linux atau macOS

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

Windows

Dengan PowerShell:

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

Setelah Anda menyelesaikan langkah-langkah di atas, Kredensial Default Aplikasi (ADC) secara implisit dapat menentukan kredensial sehingga Anda dapat menggunakan kredensial akun layanan saat menguji atau beroperasi di lingkungan non-Google.

Inisialisasi SDK seperti yang ditunjukkan:

Node.js

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

Java

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(),
});

Catatan: Opsi inisialisasi seperti databaseURL yang ditampilkan dalam contoh kode di halaman ini tidak mutlak diperlukan untuk melakukan inisialisasi SDK. Bergantung pada lingkungan deployment dan kasus penggunaan target, Anda dapat memilih untuk hanya menentukan opsi yang diperlukan.

Menggunakan token refresh OAuth 2.0

Admin SDK juga memberikan kredensial agar Anda dapat melakukan autentikasi dengan token refresh Google OAuth2:

Node.js

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

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

Java

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"),
});

Catatan: Token refresh OAuth 2.0 tidak didukung untuk terhubung ke Cloud Firestore.

Melakukan inisialisasi tanpa parameter

SDK juga dapat diinisialisasi tanpa parameter. Dalam hal ini, SDK menggunakan Kredensial Default Aplikasi Google. Karena pencarian kredensial default sepenuhnya otomatis di lingkungan Google, tanpa perlu menyediakan variabel lingkungan atau konfigurasi lain, cara menginisialisasi SDK ini sangat disarankan untuk aplikasi yang berjalan di Compute Engine, Kubernetes Engine, App Engine, dan Cloud Functions.

Agar dapat menentukan opsi inisialisasi untuk layanan seperti Realtime Database, Cloud Storage, atau Cloud Functions, gunakan variabel lingkungan FIREBASE_CONFIG. Jika isi variabel FIREBASE_CONFIG dimulai dengan {, isi tersebut akan diurai sebagai objek JSON. Jika tidak, SDK akan menganggap bahwa string tersebut adalah jalur file JSON yang berisi opsi.

Catatan: Variabel lingkungan FIREBASE_CONFIG secara otomatis disertakan dalam fungsi Cloud Functions for Firebase yang di-deploy melalui Firebase CLI.

Node.js

const app = initializeApp();

Java

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();

Setelah Admin SDK diinisialisasi, Anda dapat menggunakannya untuk menyelesaikan jenis tugas berikut:

• Mengimplementasikan autentikasi khusus
• Mengelola pengguna Firebase Authentication
• Membaca dan menulis data dari Realtime Database
• Mengirim pesan Firebase Cloud Messaging

Menginisialisasi beberapa aplikasi

Pada umumnya, Anda hanya perlu menginisialisasi satu aplikasi default. Anda dapat mengakses layanan dari aplikasi tersebut dengan dua cara yang setara:

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();

Java

// 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;

Beberapa kasus penggunaan mengharuskan Anda membuat beberapa aplikasi secara bersamaan. Misalnya, Anda mungkin ingin membaca data dari Realtime Database milik satu project Firebase dan membuat token kustom untuk project lainnya. Atau, Anda mungkin ingin mengautentikasi dua aplikasi dengan kredensial terpisah. Dengan Firebase SDK, Anda dapat membuat beberapa aplikasi secara bersamaan, masing-masing dengan informasi konfigurasinya sendiri.

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);

Java

// 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);

Catatan: Setiap instance aplikasi memiliki opsi konfigurasi dan status autentikasinya sendiri.

Menetapkan cakupan untuk Realtime Database dan Authentication

Jika menggunakan VM Google Compute Engine dengan Kredensial Default Aplikasi Google untuk Realtime Database atau Authentication, pastikan Anda juga menetapkan cakupan akses yang tepat. Untuk Realtime Database dan Authentication, Anda memerlukan cakupan yang diakhiri dengan userinfo.email dan cloud-platform atau firebase.database. Untuk memeriksa cakupan akses yang ada dan mengubahnya, jalankan perintah berikut menggunakan 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"

Menguji dengan kredensial pengguna akhir gcloud

Saat menguji Admin SDK secara lokal dengan Kredensial Default Aplikasi Google yang diperoleh dengan menjalankan gcloud auth application-default login, diperlukan perubahan tambahan untuk menggunakan Firebase Authentication karena hal berikut:

• Firebase Authentication tidak menerima kredensial pengguna akhir gcloud yang dihasilkan menggunakan client ID OAuth gcloud.
• Firebase Authentication memerlukan project ID agar diberikan saat inisialisasi untuk jenis kredensial pengguna akhir ini.

Sebagai solusinya, Anda dapat membuat Kredensial Default Aplikasi Google di gcloud menggunakan client ID OAuth 2.0 Anda sendiri. Client ID OAuth harus berupa jenis aplikasi Aplikasi desktop.

gcloud

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

Anda dapat menentukan project ID secara eksplisit saat inisialisasi aplikasi atau cukup dengan menggunakan variabel lingkungan GOOGLE_CLOUD_PROJECT. Tidak diperlukan perubahan tambahan untuk menguji kode Anda jika Anda menggunakan variabel lingkungan ini.

Untuk menentukan project ID secara eksplisit:

Node.js

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

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

Java

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>",
});

Langkah berikutnya

Mempelajari Firebase:

• Pelajari contoh aplikasi Firebase.

• Pelajari kode open source di GitHub untuk Node.js, Java, dan Python.

• Baca postingan blog terkait Admin SDK oleh salah satu pembuat Admin SDK. Misalnya: Mengakses Firestore dan Firebase melalui server proxy.

Menambahkan fitur Firebase ke aplikasi Anda:

• Menulis backend tanpa server dengan Cloud Functions.
• Menyimpan info dengan Realtime Database atau data blob dengan Cloud Storage.
• Menerima notifikasi dengan Cloud Messaging.