Ajouter le SDK Firebase Admin à votre serveur

Admin SDK est un ensemble de bibliothèques serveur qui vous permet d'interagir avec Firebase à partir d'environnements privilégiés pour effectuer des actions telles que:

  • Effectuez des requêtes et des mutations sur un service Firebase Data Connect pour la gestion de données groupées et d'autres opérations avec des droits d'administrateur complets.
  • Lire et écrire des données Realtime Database avec des droits d'administrateur complets.
  • Envoyez des messages Firebase Cloud Messaging de manière programmatique à l'aide d'une approche simple et alternative aux protocoles de serveur Firebase Cloud Messaging.
  • Générez et vérifiez des jetons d'authentification Firebase.
  • Accédez aux ressources Google Cloud telles que Cloud Storage buckets et Cloud Firestore bases de données associées à vos projets Firebase.
  • Créez votre propre console d'administration simplifiée pour effectuer des opérations telles que rechercher des données utilisateur ou modifier l'adresse e-mail d'un utilisateur pour l'authentification.

Si vous souhaitez utiliser le SDK Node.js en tant que client pour l'accès des utilisateurs finaux (par exemple, dans une application IoT ou de bureau Node.js), plutôt que pour l'accès administrateur à partir d'un environnement privilégié (comme un serveur), vous devez suivre les instructions de configuration du SDK JavaScript client.

Voici une matrice de caractéristiques indiquant les fonctionnalités Firebase compatibles dans chaque langage:

Fonctionnalité Node.js Java Python Go C#
Mintage de jetons personnalisés
Validation du jeton d'ID
Gestion des utilisateurs
Contrôler l'accès avec des revendications personnalisées
Actualiser la révocation des jetons
Importer des utilisateurs
Gestion des cookies de session
Générer des liens d'action par e-mail
Gérer les configurations de fournisseurs SAML/OIDC
Compatibilité avec l'architecture mutualisée
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
Gérer les abonnements aux sujets FCM
Cloud Storage
Cloud Firestore
Mettre des fonctions en file d'attente avec Cloud Tasks
Gestion de projets
Règles de sécurité
Gestion des modèles de ML
Firebase Remote Config
Firebase App Check
Firebase Extensions

Pour en savoir plus sur l'intégration de Admin SDK pour ces utilisations, consultez la documentation correspondante sur Realtime Database, FCM, Authentication, Remote Config et Cloud Storage. Le reste de cette page porte sur la configuration de base de Admin SDK.

Prérequis

  • Assurez-vous de disposer d'une application serveur.

  • Assurez-vous que votre serveur exécute la commande suivante en fonction du Admin SDK que vous utilisez:

    • SDK Node.js administrateur : Node.js 14 ou version ultérieure (recommandation : Node.js 18 ou version ultérieure)
      La compatibilité avec Node.js 14 et 16 est obsolète.
    • SDK Java Admin — Java 8 et versions ultérieures
    • SDK Python pour les administrateurs – Python 3.7 ou version ultérieure (recommandé : Python 3.8 ou version ultérieure)
      La compatibilité avec Python 3.7 est obsolète.
    • SDK Go Admin – Go 1.20+
    • SDK .NET Admin : .NET Framework 4.6.2 ou version ultérieure ou .NET Standard 2.0 pour .NET 6.0 ou version ultérieure

Configurer un projet et un compte de service Firebase

Pour utiliser Firebase Admin SDK, vous devez disposer des éléments suivants :

  • Un projet Firebase.
  • Un compte de service du SDK Admin Firebase pour communiquer avec Firebase Ce compte de service est créé automatiquement lorsque vous créez un projet Firebase ou ajoutez Firebase à un projet Google Cloud.
  • Un fichier de configuration contenant les identifiants de votre compte de service

Si vous n'avez pas encore de projet Firebase, vous devez en créer un dans la console Firebase. Consultez Comprendre les projets Firebase pour en savoir plus sur les projets Firebase.

Ajouter le SDK

Si vous configurez un nouveau projet, vous devez installer le SDK pour le langage de votre choix.

Node.js

Le SDK Firebase Admin Node.js est disponible sur npm. Si vous n'avez pas encore de fichier package.json, créez-en un via npm init. Installez ensuite le package npm firebase-admin et enregistrez-le dans votre package.json:

npm install firebase-admin --save

Pour utiliser le module dans votre application, demandez-le en exécutant la commande require depuis n'importe quel fichier JavaScript :

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

Si vous utilisez ES2015, vous pouvez importer le module en exécutant la commande import :

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

Java

Le SDK Java Firebase Admin est publié dans le dépôt central Maven. Pour installer la bibliothèque, déclarez-la en tant que dépendance dans votre fichier build.gradle :

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

Si vous utilisez Maven pour créer votre application, vous pouvez ajouter la dépendance suivante à pom.xml:

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

Python

Le SDK Firebase Admin pour Python est disponible via pip. Vous pouvez installer la bibliothèque pour tous les utilisateurs via sudo :

sudo pip install firebase-admin

Vous pouvez également installer la bibliothèque pour l'utilisateur actuel uniquement en transmettant l'indicateur --user:

pip install --user firebase-admin

Accéder

Vous pouvez installer Admin SDK Go à l'aide de l'utilitaire 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.0

C#

Le fichier .NET Admin SDK peut être installé à l'aide du gestionnaire de packages .NET:

Install-Package FirebaseAdmin -Version 3.0.1

Vous pouvez également l'installer à l'aide de l'utilitaire de ligne de commande dotnet :

dotnet add package FirebaseAdmin --version 3.0.1

Ou vous pouvez l'installer en ajoutant l'entrée de référence de package suivante à votre fichier .csproj :

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

Initialiser le SDK

Une fois que vous avez créé un projet Firebase, vous pouvez initialiser le SDK avec les identifiants par défaut de l'application Google. Étant donné que la recherche des identifiants par défaut est entièrement automatisée dans les environnements Google, sans avoir à fournir de variables d'environnement ni d'autre configuration, cette méthode d'initialisation du SDK est fortement recommandée pour les applications exécutées dans des environnements Google tels que Cloud Run, App Engine et Cloud Functions.

Si vous souhaitez spécifier des options d'initialisation pour des services tels que Realtime Database, Cloud Storage ou Cloud Functions, utilisez la variable d'environnement FIREBASE_CONFIG. Si le contenu de la variable FIREBASE_CONFIG commence par {, il sera analysé en tant qu'objet JSON. Sinon, le SDK suppose que la chaîne correspond au chemin d'un fichier JSON contenant les options.

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

C#

FirebaseApp.Create();

Une fois l'initialisation effectuée, vous pouvez utiliser Admin SDK pour effectuer les types de tâches suivants :

Utiliser un jeton d'actualisation OAuth 2.0

Admin SDK fournit également des identifiants qui vous permettent de vous authentifier avec un jeton d'actualisation 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)
}

C#

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

Initialiser le SDK dans des environnements autres que Google

Si vous travaillez dans un environnement de serveur autre que Google dans lequel la recherche d'identifiants par défaut ne peut pas être entièrement automatisée, vous pouvez initialiser le SDK avec un fichier de clé de compte de service exporté.

Les projets Firebase sont compatibles avec les comptes de service Google, que vous pouvez utiliser pour appeler des API de serveur Firebase à partir de votre serveur d'applications ou de votre environnement approuvé. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser des identifiants obtenus via ce compte de service pour autoriser les requêtes de serveur.

Pour authentifier un compte de service et l'autoriser à accéder aux services Firebase, vous devez générer un fichier de clé privée au format JSON.

Pour générer un fichier de clé privée pour votre compte de service :

  1. Dans la console Firebase, accédez à Paramètres > Comptes de service.

  2. Cliquez sur Generate New Private Key (Générer une nouvelle clé privée), puis confirmez en cliquant sur Generate Key (Générer la clé).

  3. Stockez de manière sécurisée le fichier JSON contenant la clé.

Lorsque vous autorisez l'accès via un compte de service, vous avez deux choix pour fournir les identifiants à votre application. Vous pouvez définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS ou transmettre explicitement le chemin d'accès à la clé du compte de service dans le code. La première option, plus sécurisée, est vivement recommandée.

Pour définir la variable d'environnement :

Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour qu'elle pointe vers le chemin du fichier JSON contenant la clé de votre compte de service. Cette variable ne s'applique qu'à la session de shell actuelle. Par conséquent, si vous ouvrez une nouvelle session, vous devez la définir à nouveau.

Linux ou macOS

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

Windows

Avec PowerShell :

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

Une fois que vous avez terminé les étapes ci-dessus, les identifiants par défaut de l'application (ADC) peuvent déterminer implicitement vos identifiants, ce qui vous permet d'utiliser les identifiants du compte de service lors des tests ou de l'exécution dans des environnements autres que Google.

Initialisez le SDK comme indiqué ci-dessous:

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

C#

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

Initialiser plusieurs applications

Dans la plupart des cas, vous n'avez qu'à initialiser une seule application par défaut. Vous pouvez accéder aux services de cette application de deux manières équivalentes :

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

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;

Dans certains cas d'utilisation, vous devez créer plusieurs applications en même temps. Par exemple, vous pouvez lire les données du Realtime Database d'un projet Firebase et générer des jetons personnalisés pour un autre projet. Vous pouvez également authentifier deux applications avec des identifiants distincts. Le SDK Firebase vous permet de créer plusieurs applications en même temps, chacune avec ses propres informations de configuration.

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

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

Définir des niveaux d'accès pour Realtime Database et Authentication

Si vous utilisez une VM Google Compute Engine avec les identifiants par défaut de l'application Google pour Realtime Database ou Authentication, veillez également à définir les niveaux d'accès appropriés. Pour Realtime Database et Authentication, vous avez besoin de champs d'application se terminant par userinfo.email et cloud-platform ou firebase.database. Pour vérifier les portées d'accès existantes et les modifier, exécutez les commandes suivantes à l'aide de 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"

Tester avec les identifiants de l'utilisateur final gcloud

Lorsque vous testez le Admin SDK localement avec les identifiants par défaut de l'application Google obtenus en exécutant gcloud auth application-default login, des modifications supplémentaires sont nécessaires pour utiliser Firebase Authentication pour les raisons suivantes:

  • Firebase Authentication n'accepte pas les identifiants utilisateur finaux gcloud générés à l'aide de l'ID client OAuth gcloud.
  • Firebase Authentication nécessite que l'ID de projet soit fourni lors de l'initialisation pour ce type d'identifiants utilisateur final.

Pour contourner ce problème, vous pouvez générer des identifiants par défaut de l'application Google dans gcloud à l'aide de votre propre ID client OAuth 2.0. L'ID client OAuth doit être de type Application de bureau.

gcloud

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

Vous pouvez spécifier explicitement l'ID du projet lors de l'initialisation de l'application ou simplement utiliser la variable d'environnement GOOGLE_CLOUD_PROJECT. Cette dernière option évite d'avoir à apporter des modifications supplémentaires pour tester votre code.

Pour spécifier explicitement l'ID du projet :

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

Étapes suivantes

En savoir plus sur Firebase:

Ajoutez les fonctionnalités Firebase à votre application: