Добавьте Firebase Admin SDK на сервер

Admin SDK – это набор серверных библиотек, позволяющих взаимодействовать с Firebase из привилегированных сред, чтобы выполнять такие действия, как:

  • Выполняйте запросы и изменения в сервисе Firebase SQL Connect для массового управления данными и других операций с полными правами администратора.
  • Чтение и запись данных Realtime Database с полными правами администратора.
  • Программная отправка сообщений Firebase Cloud Messaging с помощью простого альтернативного подхода к серверным протоколам Firebase Cloud Messaging.
  • Генерировать и проверять токены аутентификации Firebase.
  • Доступ к ресурсам Google Cloud, таким как сегменты Cloud Storage и базы данных Cloud Firestore, связанным с вашими проектами Firebase.
  • Создайте собственную упрощенную консоль администратора, чтобы выполнять такие действия, как поиск пользовательских данных или изменение адреса электронной почты пользователя для аутентификации.

Если вы хотите использовать Node.js SDK в качестве клиента для доступа конечных пользователей (например, в настольном приложении Node.js или приложении IoT), а не для доступа администратора из привилегированной среды (например, сервера), следуйте инструкциям по настройке клиентского JavaScript SDK.

В таблице ниже показано, какие функции Firebase поддерживаются в каждом языке.

Функция Node.js Java Python Проложить маршрут C# Dart
Создание собственных токенов
Проверка токена идентификации
Управление пользователями
Управление доступом с помощью настраиваемых утверждений
Отзыв токена обновления
Импорт пользователей
Управление файлами cookie сеанса
Как создать ссылки для действий в письмах
Управление конфигурациями поставщиков SAML/OIDC
Поддержка многопользовательской работы
Firebase SQL Connect
Realtime Database *
Firebase Cloud Messaging
FCM Многоадресная рассылка
Управление подписками на темы в FCM
Cloud Storage
Cloud Firestore
Как ставить функции в очередь с помощью Cloud Tasks
Управление проектами
Правила безопасности
Управление моделями машинного обучения
Firebase Remote Config
Firebase App Check
Firebase Extensions
Firebase Phone Number Verification

Чтобы узнать больше об интеграции Admin SDK для этих целей, ознакомьтесь с соответствующей документацией: Realtime Database, FCM, Authentication, Remote Config и Cloud Storage. В оставшейся части этой статьи рассказывается о базовой настройке Admin SDK.

Требования

  • Убедитесь, что у вас есть серверное приложение.

  • Убедитесь, что на сервере запущено следующее ПО (в зависимости от используемой версии Admin SDK):

    • Admin Node.js SDK – Node.js 22+
    • Admin Java SDK – Java 8+
    • Admin Python SDK – Python 3.9 и более поздних версий (рекомендуется Python 3.10 и более поздних версий).
      Поддержка Python 3.9 прекращена.
    • Admin Go SDK – Go 1.25+
    • Admin .NET SDK – .NET Framework 4.6.2+ или .NET Standard 2.0 или .NET 6.0+ (рекомендуется .NET 8.0+)
      Поддержка .NET 6.0 и 7.0 прекращена.
    • Экспериментальный Admin Dart SDK. Убедитесь, что на сервере установлен Dart SDK 3.9 или более поздней версии.

Как настроить проект Firebase и сервисный аккаунт

Чтобы использовать Firebase Admin SDK, вам понадобится следующее:

  • Проект Firebase.
  • Сервисный аккаунт Firebase Admin SDK для взаимодействия с Firebase. Этот сервисный аккаунт создается автоматически при создании проекта Firebase или добавлении Firebase в облачный проект Google Cloud.
  • Файл конфигурации с учетными данными сервисного аккаунта.

Если у вас ещё нет проекта Firebase, создайте его в консоли Firebase. Подробнее о проектах Firebase…

Добавить SDK

Если вы настраиваете новый проект, вам нужно установить SDK для выбранного языка.

Node.js

Firebase Admin Node.js SDK доступен в npm. Если у вас нет файла package.json, создайте его с помощью npm init. Затем установите пакет npm firebase-admin и сохраните его в package.json:

npm install firebase-admin --save

Чтобы использовать модуль в приложении, require его из любого файла JavaScript:

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

Если вы используете ES2015, вы можете import модуль:

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

Java

Firebase Admin Java SDK публикуется в центральном репозитории Maven. Чтобы установить библиотеку, объявите ее как зависимость в файле build.gradle:

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

Если вы используете Maven для сборки приложения, добавьте в файл pom.xml следующую зависимость:

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

Python

Firebase Admin Python SDK доступен через pip. Вы можете установить библиотеку для всех пользователей с помощью sudo:

sudo pip install firebase-admin

Вы также можете установить библиотеку только для текущего пользователя, передав флаг --user:

pip install --user firebase-admin

Проложить маршрут

Admin SDK Go можно установить с помощью утилиты 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.22.0

C#

Admin SDK .NET можно установить с помощью менеджера пакетов .NET:

Install-Package FirebaseAdmin -Version 3.7.0

Вы также можете установить его с помощью утилиты командной строки dotnet:

dotnet add package FirebaseAdmin --version 3.7.0

Вы также можете установить его, добавив в файл .csproj следующую запись:

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

Dart (экспериментальная функция)

dart pub add firebase_admin_sdk

Чтобы использовать модуль в приложении, импортируйте его, как показано ниже:

import 'package:firebase_admin_sdk';

// Also import the separate Firestore package if you're interacting with Firestore.
import 'package:google_cloud_firestore/google_cloud_firestore.dart';

Инициализируйте SDK

Создав проект Firebase, вы можете инициализировать SDK с помощью Application Default Credentials. Поскольку поиск учетных данных по умолчанию полностью автоматизирован в средах Google и не требует предоставления переменных среды или других конфигураций, этот способ инициализации SDK настоятельно рекомендуется для приложений, работающих в средах Google, таких как Firebase App Hosting, Cloud Run, App Engine и Cloud Functions for Firebase.

Чтобы указать параметры инициализации для таких сервисов, как Realtime Database, Cloud Storage или Cloud Functions, используйте переменную среды FIREBASE_CONFIG. Если содержимое переменной FIREBASE_CONFIG начинается с {, оно будет обработано как объект JSON. В противном случае SDK предполагает, что строка – это путь к файлу JSON, содержащему настройки.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Проложить маршрут

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

C#

FirebaseApp.Create();

Dart (экспериментальная функция)

final admin = FirebaseApp.initializeApp();

После инициализации вы можете использовать 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'
});

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)

Проложить маршрут

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

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = CredentialFactory.FromFile<UserCredential>("path/to/refreshToken.json").ToGoogleCredential(),
});

Инициализация SDK в средах, не относящихся к Google

Если вы работаете в среде сервера, не принадлежащего Google, в которой поиск учетных данных по умолчанию не может быть полностью автоматизирован, вы можете инициализировать SDK с помощью экспортированного файла ключа сервисного аккаунта.

Проекты Firebase поддерживают сервисные аккаунты Google, которые можно использовать для вызова серверных API Firebase с сервера приложения или из доверенной среды. Если вы разрабатываете код локально или развертываете приложение на локальном сервере, то можете использовать учетные данные, полученные с помощью этого сервисного аккаунта, для авторизации запросов к серверу.

Чтобы посмотреть все сервисные аккаунты, связанные с вашим проектом Firebase, откройте раздел Settings (Настройки) и перейдите на вкладку Service accounts (Сервисные аккаунты).

Чтобы выполнить аутентификацию сервисного аккаунта и предоставить ему доступ к сервисам Firebase, необходимо создать файл закрытого ключа в формате JSON.

Чтобы создать файл закрытого ключа для сервисного аккаунта, выполните следующие действия:

  1. В консоли Firebase перейдите в раздел Settings (Настройки) > Service accounts (Сервисные аккаунты).

  2. Нажмите Создать новый закрытый ключ, а затем подтвердите действие, нажав Создать ключ.

  3. Сохраните JSON-файл с ключом в надежном месте.

При авторизации через сервисный аккаунт у вас есть два способа предоставить учетные данные приложению. Вы можете задать переменную среды 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'
});

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

Проложить маршрут

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

C#

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

Инициализация нескольких приложений

В большинстве случаев вам нужно инициализировать только одно приложение по умолчанию. Вы можете получить доступ к сервисам этого приложения двумя эквивалентными способами:

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

Проложить маршрут

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

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;

В некоторых случаях требуется создать несколько приложений одновременно. Например, вы можете считывать данные из Realtime Database одного проекта Firebase и создавать токены для другого. Или вы можете захотеть выполнить аутентификацию двух приложений с отдельными учетными данными. 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);

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)

Проложить маршрут

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

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 с Application Default Credentials для 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

При локальном тестировании Admin SDK с Google Application Default Credentials, полученными с помощью gcloud auth application-default login, требуются дополнительные изменения для использования Firebase Authentication по следующим причинам:

  • Firebase Authentication не принимает учетные данные конечных пользователей gcloud, сгенерированные с помощью идентификатора клиента OAuth gcloud.
  • Для инициализации учетных данных конечных пользователей этого типа в Firebase Authentication необходимо указать идентификатор проекта.

В качестве временного решения вы можете сгенерировать Application Default Credentials в gcloud, используя собственный идентификатор клиента OAuth 2.0. Идентификатор клиента OAuth должен иметь тип компьютерное приложение.

gcloud

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

Вы можете указать идентификатор проекта при инициализации приложения или использовать переменную среды GOOGLE_CLOUD_PROJECT. Последний вариант позволяет избежать необходимости вносить какие-либо дополнительные изменения для тестирования вашего кода.

Чтобы явно указать идентификатор проекта, выполните следующие действия:

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)

Проложить маршрут

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 в приложение: