Agrega el SDK de Firebase Admin a tu servidor

Admin SDK es un conjunto de bibliotecas de servidor que te permite interactuar con Firebase desde entornos con privilegios a fin de ejecutar acciones como las siguientes:

  • Realizar consultas y mutaciones en un servicio Firebase Data Connect para la administración masiva de datos y otras operaciones con privilegios de administrador completos.
  • Leer y escribir datos de Realtime Database con todos los privilegios de administrador
  • Enviar mensajes Firebase Cloud Messaging de manera programática con un enfoque alternativo a los protocolos del servidor Firebase Cloud Messaging
  • Generar y verificar tokens de autenticación de Firebase
  • Acceder a recursos de Google Cloud, como buckets de Cloud Storage y bases de datos de Cloud Firestore asociadas a tus proyectos de Firebase.
  • Crear tu propia consola del administrador simplificada para ejecutar tareas como buscar datos del usuario o cambiar la dirección de correo electrónico de un usuario para la autenticación

Si quieres usar el SDK de Node.js como cliente para el acceso de los usuarios finales (por ejemplo, en una aplicación de Node.js para computadoras o IoT) y no para el acceso de administrador desde un entorno con privilegios (como un servidor), sigue las instrucciones para configurar el SDK cliente de JavaScript.

A continuación, se muestra una matriz de funciones de Firebase que indica cuáles son compatibles con cada lenguaje:

Función Node.js Java Python Go C#
Creación de tokens personalizados
Verificación de token de ID
Administración de usuarios
Control del acceso con reclamaciones personalizadas
Revocación de tokens de actualización
Importación de usuarios
Administración de cookies de sesión
Generación de vínculos de acciones de correo electrónico
Administración de configuraciones del proveedor SAML/OIDC
Compatibilidad con los multiusuarios
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
Multicast de FCM
Administra suscripciones a temas de FCM
Cloud Storage
Cloud Firestore
Pon funciones en cola con Cloud Tasks
Administración de proyectos
Reglas de seguridad
Administración de modelos de AA
Firebase Remote Config
Firebase App Check
Firebase Extensions

Si quieres obtener más información sobre la integración de Admin SDK para estos usos, consulta la documentación de Realtime Database, FCM, Authentication, Remote Config y Cloud Storage. El resto de esta página se enfoca en la configuración básica de Admin SDK.

Requisitos previos

  • Asegúrate de tener una app de servidor.

  • Asegúrate de que tu servidor ejecute lo siguiente según el Admin SDK que usas:

    • SDK de Admin para Node.js: Node.js 18 o una versión más reciente
    • SDK de Admin para Java: Java 8 y versiones posteriores
    • SDK de Admin para Python: Python 3.7 o versiones posteriores (se recomienda Python 3.8 o versiones posteriores)
      La compatibilidad con Python 3.7 está obsoleta.
    • SDK de Admin para Go: Go 1.21 o versiones posteriores
    • SDK de Admin para .NET: .NET Framework 4.6.2 o versiones posteriores, o .NET Standard 2.0 para .NET 6.0 o versiones posteriores

Configura un proyecto y una cuenta de servicio de Firebase

Para usar Firebase Admin SDK, necesitarás lo siguiente:

  • Un proyecto de Firebase
  • Una cuenta de servicio del SDK de Firebase Admin para que se comunique con Firebase. Esta cuenta de servicio se crea automáticamente cuando creas un proyecto de Firebase o cuando agregas Firebase a un proyecto de Google Cloud
  • Un archivo de configuración con las credenciales de tu cuenta de servicio

Si aún no tienes un proyecto de Firebase, debes crear uno en Firebase console. Consulta la Información sobre los proyectos de Firebase para obtener más detalles sobre el tema.

Agrega el SDK

Si estás configurando un nuevo proyecto, deberás instalar el SDK correspondiente al idioma de tu preferencia.

Node.js

El SDK de Firebase Admin para Node.js está disponible en npm. Si aún no tienes un archivo package.json, crea uno a través de npm init. A continuación, instala el paquete de npm de firebase-admin y guárdalo en tu package.json:

npm install firebase-admin --save

Para usar el módulo en tu aplicación, utiliza require desde cualquier archivo JavaScript:

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

Si usas ES2015, puedes usar la función import para importar el módulo:

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

Java

El SDK de Firebase Admin para Java se publica en el repositorio central de Maven. Para instalar la biblioteca, debes declararla como una dependencia en el archivo build.gradle:

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

Si usas Maven para crear la aplicación, puedes agregar la siguiente dependencia a pom.xml:

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

Python

El SDK de Firebase Admin para Python está disponible mediante pip. Puedes instalar la biblioteca para todos los usuarios a través de sudo:

sudo pip install firebase-admin

O bien, si deseas instalar la biblioteca solo para el usuario actual, pasa la marca --user:

pip install --user firebase-admin

Go

Admin SDK de Go se puede instalar con la utilidad 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.1

C#

El Admin SDK de .NET se puede instalar con el administrador de paquetes de .NET:

Install-Package FirebaseAdmin -Version 3.1.0

De manera alternativa, instálalo mediante la utilidad de línea de comandos de dotnet:

dotnet add package FirebaseAdmin --version 3.1.0

O bien, puedes hacerlo si agregas la siguiente entrada de referencia de paquete en el archivo .csproj:

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

Inicializa el SDK

Una vez que hayas creado un proyecto de Firebase, puedes inicializar el SDK con las credenciales predeterminadas de la aplicación de Google. Debido a que la búsqueda de credenciales predeterminada está completamente automatizada en los entornos de Google, sin necesidad de suministrar variables de entorno o alguna otra configuración, se recomienda esta manera de inicializar el SDK para las aplicaciones que se ejecutan en los entornos de Google, como Cloud Run, App Engine y Cloud Functions.

Si, de manera opcional, quieres especificar opciones de inicialización para servicios como Realtime Database, Cloud Storage o Cloud Functions, usa la variable de entorno FIREBASE_CONFIG. Si el contenido de la variable FIREBASE_CONFIG comienza con un {, se analizará como un objeto JSON. De lo contrario, el SDK supone que la string es la ruta de acceso de un archivo JSON que contiene las opciones.

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

Una vez que se inicializa, puedes usar Admin SDK para realizar los siguientes tipos de tareas:

Utiliza un token de actualización de OAuth 2.0

Admin SDK también proporciona una credencial que te permite autenticar con un token de actualización de 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"),
});

Inicializa el SDK en entornos de terceros

Si trabajas en un entorno de servidor que no es de Google en el que la búsqueda de credenciales predeterminada no se puede automatizar por completo, puedes inicializar el SDK con un archivo de claves de la cuenta de servicio exportado.

Los proyectos de Firebase son compatibles con las cuentas de servicio de Google, por lo que puedes llamar a las APIs del servidor de Firebase desde tu servidor de apps o un entorno de confianza. Si desarrollas código o implementas tu aplicación de manera local, puedes usar las credenciales obtenidas mediante la cuenta de servicio para autorizar las solicitudes del servidor.

Para autenticar una cuenta de servicio y autorizar su acceso a los servicios de Firebase, debes generar un archivo de claves privadas en formato JSON.

Sigue estos pasos a fin de generar un archivo de claves privadas para la cuenta de servicio:

  1. En la consola de Firebase, abre Configuración > Cuentas de servicio.

  2. Haz clic en Generar nueva clave privada y luego en Generar clave para confirmar.

  3. Almacena de forma segura el archivo JSON que contiene la clave.

Cuando autorices mediante una cuenta de servicio, tienes dos opciones para proporcionar las credenciales a la aplicación. Puedes configurar la variable de entorno GOOGLE_APPLICATION_CREDENTIALS o pasar la ruta a la clave de la cuenta de servicio en el código de forma explícita. Recomendamos enfáticamente que uses la primera opción, ya que es más segura.

Para configurar la variable de entorno, haz lo siguiente:

Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS con la ruta del archivo JSON que contiene la clave de tu cuenta de servicio. Esta variable solo se aplica a la sesión actual de Cloud Shell. Por lo tanto, si abres una sesión nueva, deberás volver a configurar la variable.

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"

Cuando completes los pasos anteriores, el servicio de credenciales predeterminadas de aplicación (ADC) puede determinar de forma implícita tus credenciales, lo que te permite usar credenciales de cuentas de servicio cuando realizas pruebas o ejecutas aplicaciones en entornos de terceros.

Inicializa el SDK, como se muestra a continuación:

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(),
    ProjectId = "my-project-id",
});

FirebaseAppSnippets.cs

Inicializa varias apps

En la mayoría de los casos, solo debes inicializar una sola app predeterminada. Puedes acceder a los servicios mediante esa app de dos maneras que son equivalentes:

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;

En algunos casos de uso, tendrás que crear varias apps al mismo tiempo. Por ejemplo, tal vez necesites leer datos de Realtime Database de un proyecto de Firebase y generar tokens personalizados para otro proyecto. O tal vez necesites autenticar dos apps con credenciales distintas. El SDK de Firebase te permite crear varias apps al mismo tiempo, cada una de las cuales tendrá su propia información de configuración.

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

Configura los permisos para Realtime Database y Authentication

Si usas una VM de Google Compute Engine con las credenciales predeterminadas de la aplicación de Google para Realtime Database o Authentication, asegúrate de configurar también los permisos de acceso correctos. Para Realtime Database y Authentication, necesitas permisos que terminen en userinfo.email y cloud-platform o firebase.database. Para verificar los alcances de acceso existentes y cambiarlos, ejecuta los siguientes comandos con 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"

Realiza pruebas con credenciales de usuario final de gcloud

Cuando pruebas Admin SDK de forma local con las Credenciales predeterminadas de la aplicación de Google que se obtienen ejecutando gcloud auth application-default login, debes realizar cambios adicionales para usar Firebase Authentication debido a los siguientes factores:

  • Firebase Authentication no acepta credenciales de usuario final de gcloud generadas con el ID de cliente de OAuth de gcloud.
  • Firebase Authentication requiere que se proporcione el ID del proyecto en la inicialización para este tipo de credenciales de usuario final.

Como solución alternativa, puedes generar las Credenciales predeterminadas de la aplicación de Google en gcloud con tu propio ID de cliente de OAuth 2.0. El ID de cliente de OAuth debe ser un tipo de aplicación para computadoras.

gcloud

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

Puedes especificar el ID del proyecto de forma explícita en la inicialización de la app, o solo usar la variable de entorno GOOGLE_CLOUD_PROJECT. Con la variable, evitas realizar cambios adicionales para probar tu código.

Sigue estos pasos para especificar explícitamente el ID del proyecto:

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

Próximos pasos

Obtén información acerca de Firebase:

Agrega funciones de Firebase a la app: