Aggiungi l'SDK Admin Firebase al server

Admin SDK è un insieme di librerie server che ti consente di interagire con Firebase da ambienti privilegiati per eseguire azioni come:

  • Esegui query e mutazioni su un servizio Firebase Data Connect per la gestione collettiva dei dati e altre operazioni con privilegi amministrativi completi.
  • Leggi e scrivi dati Realtime Database con privilegi amministrativi completi.
  • Invia messaggi Firebase Cloud Messaging in modo programmatico utilizzando un approccio semplice e alternativo ai protocolli dei server Firebase Cloud Messaging.
  • Genera e verifica i token di autenticazione Firebase.
  • Accedi alle risorse Google Cloud, come i bucket Cloud Storage e i database Cloud Firestore associati ai tuoi progetti Firebase.
  • Crea la tua Console di amministrazione semplificata per eseguire operazioni come cercare i dati utente o modificare l'indirizzo email di un utente per l'autenticazione.

Se vuoi utilizzare l'SDK Node.js come client per l'accesso degli utenti finali (ad esempio in un'applicazione IoT o desktop Node.js), anziché l'accesso amministrativo da un ambiente privilegiato (come un server), devi seguire le istruzioni per configurare l'SDK JavaScript client.

Di seguito è riportata una matrice delle funzionalità che mostra quali funzionalità di Firebase sono supportate in ogni lingua:

Funzionalità Node.js Java Python Vai C#
Minting di token personalizzati
Verifica del token ID
Gestione utenti
Controllare l'accesso con rivendicazioni personalizzate
Revoca del token di aggiornamento
Importa utenti
Gestione dei cookie di sessione
Generare link di azioni email
Gestione delle configurazioni dei provider SAML/OIDC
Supporto del multitenancy
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
FCM Multicast
Gestire gli FCM abbonamenti ai temi
Cloud Storage
Cloud Firestore
Mettere in coda le funzioni con Cloud Tasks
Project management
Regole di sicurezza
Gestione dei modelli ML
Firebase Remote Config
Firebase App Check
Firebase Extensions

Per scoprire di più sull'integrazione di Admin SDK per questi utilizzi, consulta la documentazione corrispondente di Realtime Database, FCM, Authentication, Remote Config e Cloud Storage. Il resto di questa pagina è incentrato sulla configurazione di base del Admin SDK.

Prerequisiti

  • Assicurati di avere un'app server.

  • Assicurati che il server esegua quanto segue, a seconda del Admin SDK utilizzato:

    • SDK Admin Node.js - Node.js 18 e versioni successive
    • SDK Java Admin - Java 8 e versioni successive
    • SDK Python per amministratore: Python 3.7 e versioni successive (consigliato Python 3.8 e versioni successive)
      Il supporto di Python 3.7 è deprecato.
    • SDK Admin Go - Go 1.21 e versioni successive
    • SDK .NET Admin: .NET Framework 4.6.2 o versioni successive o .NET Standard 2.0 per .NET 6.0 o versioni successive

Configurare un progetto e un account di servizio Firebase

Per utilizzare Firebase Admin SDK, sono necessari:

  • Un progetto Firebase.
  • Un account di servizio SDK Firebase Admin per comunicare con Firebase. Questo account di servizio viene creato automaticamente quando crei un progetto Firebase o aggiungi Firebase a un progetto Google Cloud.
  • Un file di configurazione con le credenziali del tuo account di servizio.

Se non hai ancora un progetto Firebase, devi crearne uno nella console Firebase. Consulta Informazioni sui progetti Firebase per saperne di più su questi progetti.

Aggiungi l'SDK

Se stai configurando un nuovo progetto, devi installare l'SDK per la lingua che preferisci.

Node.js

L'SDK Firebase Admin per Node.js è disponibile su npm. Se non hai già un file package.json, creane uno tramite npm init. Poi, installa il pacchetto npm firebase-admin e salvalo in package.json:

npm install firebase-admin --save

Per utilizzare il modulo nella tua applicazione, require da qualsiasi file JavaScript:

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

Se utilizzi ES2015, puoi import il modulo:

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

Java

L'SDK Java Firebase Admin viene pubblicato nel repository centrale Maven. Per installare la libreria, dichiarala come dipendenza nel file build.gradle:

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

Se utilizzi Maven per compilare l'applicazione, puoi aggiungere la seguente dipendenza al file pom.xml:

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

Python

L'SDK Firebase Admin per Python è disponibile tramite pip. Puoi installare la libreria per tutti gli utenti tramite sudo:

sudo pip install firebase-admin

In alternativa, puoi installare la libreria solo per l'utente corrente passando il flag --user:

pip install --user firebase-admin

Vai

Admin SDK Go può essere installato utilizzando l'utilità 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#

Admin SDK .NET può essere installato utilizzando il gestore dei pacchetti .NET:

Install-Package FirebaseAdmin -Version 3.1.0

In alternativa, installalo utilizzando l'utilità a riga di comando dotnet:

dotnet add package FirebaseAdmin --version 3.1.0

In alternativa, puoi installarlo aggiungendo la seguente voce di riferimento del pacchetto al tuo file .csproj:

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

Inizializza l'SDK

Dopo aver creato un progetto Firebase, puoi inizializzare l'SDK con le credenziali predefinite dell'applicazione Google. Poiché la ricerca delle credenziali predefinite è completamente automatizzata negli ambienti Google, senza la necessità di fornire variabili di ambiente o altra configurazione, questo metodo di inizializzazione dell'SDK è vivamente consigliato per le applicazioni in esecuzione negli ambienti Google come Cloud Run, App Engine e Cloud Functions.

Per specificare facoltativamente le opzioni di inizializzazione per servizi come Realtime Database, Cloud Storage o Cloud Functions, utilizza la variabile di ambiente FIREBASE_CONFIG. Se i contenuti della variabile FIREBASE_CONFIG iniziano con un {, verranno analizzati come oggetto JSON. In caso contrario, l'SDK presume che la stringa sia il percorso di un file JSON contenente le opzioni.

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Python

default_app = firebase_admin.initialize_app()

Vai

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

C#

FirebaseApp.Create();

Una volta inizializzato, puoi utilizzare Admin SDK per eseguire i seguenti tipi di attività:

Utilizzo di un token di aggiornamento OAuth 2.0

Admin SDK fornisce anche una credenziale che ti consente di autenticarti con un token di aggiornamento 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)

Vai

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

Inizializzare l'SDK in ambienti non Google

Se utilizzi un ambiente di server non Google in cui la ricerca delle credenziali predefinite non può essere completamente automatizzata, puoi inizializzare l'SDK con un file della chiave dell'account di servizio esportato.

I progetti Firebase supportano gli account di servizio Google, che puoi utilizzare per chiamare le API di server Firebase dal server dell'app o dall'ambiente attendibile. Se stai sviluppando codice localmente o esegui il deployment dell'applicazione on-premise, puoi utilizzare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste al server.

Per autenticare un account di servizio e autorizzarlo ad accedere ai servizi Firebase, devi generare un file della chiave privata in formato JSON.

Per generare un file della chiave privata per il tuo account di servizio:

  1. Nella console Firebase, apri Impostazioni > Account di servizio.

  2. Fai clic su Genera nuova chiave privata, poi conferma facendo clic su Genera chiave.

  3. Memorizza in modo sicuro il file JSON contenente la chiave.

Quando esegui l'autorizzazione tramite un account di servizio, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS o passare esplicitamente il percorso della chiave dell'account di servizio nel codice. La prima opzione è più sicura ed è vivamente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave dell'account di servizio. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo la variabile.

Linux o macOS

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

Windows

Con PowerShell:

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

Dopo aver completato i passaggi precedenti, le credenziali predefinite dell'applicazione (ADC) possono determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account servizio durante i test o l'esecuzione in ambienti non Google.

Inizializza l'SDK come mostrato:

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

Vai

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

Inizializzare più app

Nella maggior parte dei casi, devi solo inizializzare un'unica app predefinita. Puoi accedere ai servizi da questa app in due modi equivalenti:

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

Vai

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

Alcuni casi d'uso richiedono la creazione di più app contemporaneamente. Ad esempio, potresti voler leggere i dati del Realtime Database di un progetto Firebase e coniare token personalizzati per un altro progetto. In alternativa, potresti voler autenticare due app con credenziali separate. L'SDK Firebase ti consente di creare più app contemporaneamente, ognuna con le proprie informazioni di configurazione.

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)

Vai

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

Imposta gli ambiti per Realtime Database e Authentication

Se utilizzi una VM Google Compute Engine con le Credenziali predefinite dell'applicazione Google per Realtime Database o Authentication, assicurati di impostare anche gli ambiti di accesso corretti. Per Realtime Database e Authentication, sono necessari ambiti che terminano con userinfo.email e cloud-platform o firebase.database. Per controllare gli scopi di accesso esistenti e modificarli, esegui i seguenti comandi utilizzando 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"

Test con le credenziali utente finale di gcloud

Quando testi Admin SDK in locale con le credenziali predefinite dell'applicazione Google ottenute eseguendo gcloud auth application-default login, sono necessarie modifiche aggiuntive per utilizzare Firebase Authentication per i seguenti motivi:

  • Firebase Authentication non accetta le credenziali utente finale di gcloud generate utilizzando l'ID client OAuth di gcloud.
  • Firebase Authentication richiede che l'ID progetto venga fornito all'inizializzazione per questo tipo di credenziali utente finale.

Come soluzione alternativa, puoi generare le credenziali predefinite per le applicazioni Google in gcloud utilizzando il tuo ID client OAuth 2.0. L'ID client OAuth deve essere un tipo di applicazione App desktop.

gcloud

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

Puoi specificare l'ID progetto esplicitamente all'inizializzazione dell'app o semplicemente utilizzare la variabile di ambienteGOOGLE_CLOUD_PROJECT. Quest'ultimo evita di dover apportare altre modifiche per testare il codice.

Per specificare esplicitamente l'ID progetto:

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)

Vai

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

Passaggi successivi

Scopri di più su Firebase:

Aggiungi le funzionalità di Firebase alla tua app: