Aggiungi l'SDK Admin Firebase al server

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

• Esegui query e mutazioni su un servizio Firebase SQL Connect per la gestione dei dati collettivi e altre operazioni con privilegi amministrativi completi.
• Leggere e scrivere dati di Realtime Database con privilegi amministrativi completi.
• Invia messaggi Firebase Cloud Messaging in modo programmatico utilizzando un approccio semplice e alternativo ai protocolli del server Firebase Cloud Messaging.
• Generare e verificare i token di autenticazione di Firebase.
• Accedere 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 la ricerca dei dati utente o la modifica dell'indirizzo email di un utente per l'autenticazione.

Se ti interessa utilizzare l'SDK Node.js come client per l'accesso degli utenti finali (ad esempio, in un'applicazione desktop o IoT Node.js), anziché per l'accesso amministrativo da un ambiente con privilegi (come un server), devi seguire le istruzioni per la configurazione dell'SDK JavaScript client.

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

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

Prerequisiti

• Assicurati di avere un'app server.

• Assicurati che sul tuo server sia in esecuzione quanto segue, a seconda di quale Admin SDK utilizzi:

  • SDK Admin Node.js - Node.js 22+
    
  • SDK Admin Java: Java 8 e versioni successive
  • SDK Admin Python: Python 3.9 o versioni successive (consigliato Python 3.10 o versioni successive)
    Il supporto di Python 3.9 è deprecato.
  • SDK Admin Go: Go 1.25 e versioni successive
  • SDK Admin .NET: .NET Framework 4.6.2 o versioni successive, .NET Standard 2.0 o .NET 6.0 o versioni successive (consigliato .NET 8.0 o versioni successive)
    Il supporto di .NET 6.0 e 7.0 è stato ritirato.
  • SDK Admin Dart sperimentale: assicurati che sul tuo server sia in esecuzione l'SDK Dart 3.9 o versioni successive.

Configura un progetto Firebase e un service account

Per utilizzare Firebase Admin SDK, devi disporre di quanto segue:

• Un progetto Firebase.
• Un service account SDK Firebase Admin per comunicare con Firebase. Questo service account 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 service account.

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

Aggiungi l'SDK

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

npm install firebase-admin --save

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

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

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

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

sudo pip install firebase-admin

pip install --user firebase-admin

go get firebase.google.com/go/v4@latest

go get firebase.google.com/go/v4@4.22.0

Install-Package FirebaseAdmin -Version 3.7.0

dotnet add package FirebaseAdmin --version 3.7.0

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

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

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 altre configurazioni, questo modo di inizializzare l'SDK è vivamente consigliato per le applicazioni in esecuzione in ambienti Google come Firebase App Hosting, Cloud Run, App Engine e Cloud Functions for Firebase.

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 {, verranno analizzati come oggetto JSON. In caso contrario, l'SDK presuppone che la stringa sia il percorso di un file JSON contenente le opzioni.

const app = initializeApp();

FirebaseApp.initializeApp();

default_app = firebase_admin.initialize_app()

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

FirebaseApp.Create();

final admin = FirebaseApp.initializeApp();

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

• Implementa l'autenticazione personalizzata
• Gestisci gli utenti di Firebase Authentication
• Esegui query e mutazioni amministrative su un servizio Firebase SQL Connect.
• Leggi e scrivi dati da Realtime Database
• Invia messaggi Firebase Cloud Messaging

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:

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

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)
}
init.go

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

Inizializza l'SDK in ambienti non Google

Se lavori in un ambiente 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 i service account Google, che puoi utilizzare per chiamare le API del server Firebase dal tuo server dell'app o dall'ambiente attendibile. Se stai sviluppando codice localmente o eseguendo il deployment della tua applicazione on-premise, puoi utilizzare le credenziali ottenute utilizzando questo service account per autorizzare le richieste del server.

Puoi visualizzare tutti i service account del tuo progetto Firebase nella scheda settings Impostazioni > Service account.

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

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

1. Nella console Firebase, vai a settings Impostazioni > scheda Service account.

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

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

Quando esegui l'autorizzazione tramite un service account, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS o passare esplicitamente il percorso alla chiave del service account 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.

export GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_FILE_PATH"

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

Inizializza l'SDK come mostrato:

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

default_app = firebase_admin.initialize_app()

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

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

Inizializza più app

Nella maggior parte dei casi, devi inizializzare una singola app predefinita. Puoi accedere ai servizi di quell'app in due modi equivalenti:

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

# 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)
}
init.go

// 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 dal 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, ciascuna con le proprie informazioni di configurazione.

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

# 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)
}
init.go

// 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 di Google Compute Engine con Credenziali predefinite dell'applicazione Google per Realtime Database o Authentication, assicurati di impostare anche gli ambiti di accesso corretti. Per Realtime Database e Authentication, devi avere ambiti che terminano con userinfo.email e cloud-platform o firebase.database. Per controllare gli ambiti di accesso esistenti e modificarli, completa i seguenti passaggi utilizzando gcloud:

1. Controlla l'attuale service account e gli ambiti di accesso della VM:

   gcloud compute instances describe \
     INSTANCE_NAME \
     --format=json
   

2. Individua la sezione serviceAccounts nell'output e prendi nota dell'indirizzo email del service account. Ad esempio:

   {
     "serviceAccounts": [
       {
         "email": "SERVICE_ACCOUNT_EMAIL",
         "scopes": [
           "https://www.googleapis.com/auth/cloud-platform",
           "https://www.googleapis.com/auth/userinfo.email"
         ]
       }
     ]
   }
   

3. Arresta la VM, quindi aggiorna i relativi ambiti di accesso utilizzando l'indirizzo email del service account del passaggio precedente:

   gcloud compute instances set-service-account \
     INSTANCE_NAME \
     --service-account "SERVICE_ACCOUNT_EMAIL" \
     --scopes "https://www.googleapis.com/auth/firebase.database,https://www.googleapis.com/auth/userinfo.email"
   

Esegui il test con le credenziali utente finale gcloud

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

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

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

gcloud auth application-default login \
  --client-id-file=PATH_TO_CLIENT_ID_FILE

Puoi specificare l'ID progetto in modo esplicito durante l'inizializzazione dell'app o semplicemente utilizzare la variabile di ambiente GOOGLE_CLOUD_PROJECT. Quest'ultimo evita la necessità di apportare ulteriori modifiche per testare il codice.

Per specificare esplicitamente l'ID progetto:

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

initializeApp({
  credential: applicationDefault(),
  projectId: 'PROJECT_ID',
});

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setProjectId("PROJECT_ID")
    .build();

FirebaseApp.initializeApp(options);

app_options = {'projectId': 'PROJECT_ID'}
default_app = firebase_admin.initialize_app(options=app_options)

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

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

Passaggi successivi

Scopri di più su Firebase:

• Esplora le app Firebase di esempio.

• Esplora il codice sorgente open source in GitHub per Node.js, Java e Python.

• Leggi i blog post relativi a Admin SDK di uno dei creatori di Admin SDK. Ad esempio: Accesso a Firestore e Firebase tramite un server proxy.

Aggiungi le funzionalità di Firebase alla tua app:

• Scrivere un backend serverless con Cloud Functions.
• Archivia le informazioni con Realtime Database o i dati blob con Cloud Storage.
• Ricevere notifiche con Cloud Messaging.