Adicionar o SDK Admin do Firebase ao servidor

O Admin SDK é um conjunto de bibliotecas de servidor que permite interagir com o Firebase usando ambientes privilegiados para executar ações como:

  • Executar consultas e mutações em um serviço Firebase Data Connect para gerenciamento de dados em massa e outras operações com privilégios de administrador completos.
  • ler e gravar dados do Realtime Database com privilégios completos de administrador;
  • enviar mensagens do Firebase Cloud Messaging de maneira programática usando uma abordagem simples e alternativa aos protocolos de servidor do Firebase Cloud Messaging;
  • gerar e verificar os tokens do Auth do Firebase;
  • acessar recursos do Google Cloud, como buckets do Cloud Storage e bancos de dados do Cloud Firestore associados aos seus projetos do Firebase;
  • criar seu próprio console de administração simplificado para realizar ações como procurar dados do usuário ou alterar o endereço de e-mail de um usuário para fazer a autenticação.

Se você tiver interesse em usar o SDK do Node.js como um cliente para permitir o acesso de usuários finais, como em um computador com Node.js ou um aplicativo de IoT, em vez de usar o acesso de administrador em um ambiente privilegiado (como um servidor), siga as instruções sobre como configurar o SDK para JavaScript do cliente.

Veja a seguir uma matriz de recursos que mostra quais recursos do Firebase são compatíveis com cada linguagem:

Recurso Node.js Java Python Go C#
Criação de tokens personalizada
Verificação de tokens de ID
Gerenciamento de usuários
Acesso de controle com declarações personalizadas
Revogação do token de atualização
Importação de usuários
Gerenciamento de cookies de sessão
Geração de links de ação de e-mail
Gerenciamento de configurações do provedor SAML/OIDC
Suporte a multilocação
Firebase Data Connect
Realtime Database *
Firebase Cloud Messaging
Multicast do FCM
Gerenciar inscrições de tópicos do FCM
Cloud Storage
Cloud Firestore
Enfileirar funções com o Cloud Tasks
Gerenciamento de projetos
Regras de segurança
Gerenciamento de modelos de ML
Firebase Remote Config
Firebase App Check
Firebase Extensions

Para saber mais sobre a integração do Admin SDK para esses usos, consulte a documentação do Realtime Database, FCM, Authentication, Remote Config, e Cloud Storage. O restante desta página se concentra na configuração básica do Admin SDK.

Pré-requisitos

  • Verifique se você tem um app de servidor.

  • Verifique se o servidor executa os parâmetros a seguir, dependendo do Admin SDK usado:

    • SDK Admin para Node.js: Node.js 18 ou mais recente
    • SDK Admin para Java 8 ou mais recente
    • SDK Admin para Python 3.7 ou mais recente (recomendamos o Python 3.8 ou mais recente)
      O suporte ao Python 3.7 foi descontinuado.
    • SDK Admin para Go 1.21 ou mais recente
    • SDK Admin para .NET Framework 4.6.2 ou mais recente ou .NET Standard 2.0 para .NET 6.0 ou mais recente

Configurar um projeto e uma conta de serviço do Firebase

Para usar o Firebase Admin SDK, você precisa do seguinte:

  • um projeto do Firebase;
  • uma conta de serviço do SDK Admin do Firebase para se comunicar com o Firebase. Ela é gerada automaticamente quando você cria um projeto do Firebase ou adiciona a plataforma a um projeto do Google Cloud;
  • um arquivo de configuração com as credenciais da sua conta de serviço.

Se você ainda não tem um projeto do Firebase, crie um no console do Firebase. Consulte Noções básicas sobre projetos do Firebase para mais informações.

Adicionar o SDK

Se você estiver configurando um novo projeto, será necessário instalar o SDK para a linguagem de sua escolha.

Node.js

O SDK Admin para Node.js do Firebase está disponível em NPM. Se você ainda não tiver um arquivo package.json, crie um via npm init. Em seguida, instale o pacote npm firebase-admin e salve-o em package.json:

npm install firebase-admin --save

Para usar o módulo no seu aplicativo, utilize o método require em qualquer arquivo JavaScript:

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

Se você estiver usando o ES2015, utilize o método import para importar o módulo:

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

Java

O SDK Admin para JavaScript do Firebase foi publicado no repositório Maven central. Para instalar a biblioteca, declare-a como uma dependência no seu arquivo build.gradle:

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

Se você usa o Maven para criar seu app, adicione esta dependência ao pom.xml:

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

Python

O SDK Admin para Python do Firebase está disponível via PIP. Você pode instalar a biblioteca para todos os usuários via sudo:

sudo pip install firebase-admin

Ou, para instalar a biblioteca apenas para o usuário atual, passe a flag --user:

pip install --user firebase-admin

Go

O Admin SDK para Go pode ser instalado usando o utilitário 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#

O Admin SDK para .NET pode ser instalado usando o gerenciador de pacotes .NET:

Install-Package FirebaseAdmin -Version 3.1.0

Se preferir, instale-o com o utilitário de linha de comando dotnet:

dotnet add package FirebaseAdmin --version 3.1.0

Ou você pode instalá-lo adicionando a seguinte entrada de referência do pacote ao seu arquivo .csproj:

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

Inicializar o SDK

Depois de criar um projeto do Firebase, é possível inicializar o SDK com o Application Default Credentials do Google. Como a pesquisa de credenciais padrão é totalmente automatizada nos ambientes do Google, sem a necessidade de fornecer variáveis de ambiente ou outras configurações, esse método de inicializar o SDK é altamente recomendado para aplicativos executados em ambientes do Google, como o Cloud Run, App Engine e Cloud Functions.

Para especificar opções de inicialização para serviços como Realtime Database, Cloud Storage ou Cloud Functions, use a variável de ambiente FIREBASE_CONFIG. Caso o conteúdo da variável FIREBASE_CONFIG comece com um {, ele será analisado como um objeto JSON. Caso contrário, a string será tratada pelo SDK como o caminho de um arquivo JSON que contém as opções.

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

Depois de inicializado, você pode usar Admin SDK para realizar os seguintes tipos de tarefas:

Como usar um token de atualização do OAuth 2.0

O Admin SDK também fornece uma credencial que permite a autenticação com um token de atualização do 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"),
});

Inicializar o SDK em ambientes que não são do Google

Se você está trabalhando em um ambiente de servidor que não seja do Google em que a pesquisa de credenciais padrão não é totalmente automatizada, inicialize o SDK com um arquivo de chave da conta de serviço exportado.

Os projetos do Firebase oferecem suporte a contas de serviço do Google, que você pode usar para chamar APIs do servidor do Firebase utilizando seu servidor de aplicativos ou um ambiente confiável. Se você estiver desenvolvendo código ou implantando o aplicativo localmente, será possível usar credenciais recebidas por essa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la para acessar os serviços do Firebase, gere um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada da conta de serviço, siga estas etapas:

  1. No console Firebase, abra Configurações > Contas de serviço.

  2. Clique em Gerar nova chave privada e selecione Gerar chave para confirmar.

  3. Armazene com segurança o arquivo JSON que contém a chave.

Ao autorizar usando uma conta de serviço, existem duas opções para fornecer as credenciais ao seu aplicativo. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou transmita explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é altamente recomendável.

Para definir a variável de ambiente:

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

Linux ou macOS

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

Windows

Com o PowerShell:

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

Depois de concluir as etapas acima, o Application Default Credentials (ADC) poderá determinar implicitamente suas credenciais, permitindo que você use as credenciais da conta de serviço ao testar ou executar em ambientes que não são do Google.

Inicialize o SDK como mostrado:

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

Inicializar vários aplicativos

Na maioria dos casos, você só precisa inicializar um único aplicativo padrão. Você pode acessar serviços fora desse aplicativo de duas maneiras 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)
}

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;

Alguns casos de uso exigem que você crie vários aplicativos ao mesmo tempo. Por exemplo, talvez você queira ler dados do Realtime Database de um projeto do Firebase e criar tokens personalizados para outro projeto. Ou talvez autenticar dois aplicativos com credenciais individuais. Com o SDK do Firebase, você cria vários apps ao mesmo tempo, cada um com as próprias informações de configuração.

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

Definir escopos para Realtime Database e Authentication

Se você estiver usando uma VM do Google Compute Engine com o Application Default Credentials do Google para Realtime Database ou Authentication, configure também os escopos de acesso corretos. Para Realtime Database e Authentication, você precisa de escopos que terminem em userinfo.email e cloud-platform ou firebase.database. Para verificar os escopos de acesso existentes e alterá-los, execute os comandos abaixo usando a 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"

Como testar com credenciais de usuário final da gcloud

Ao testar o Admin SDK localmente com o Application Default Credentials do Google ao executar gcloud auth application-default login, mais mudanças são necessárias para usar o Firebase Authentication devido ao seguinte:

  • O Firebase Authentication não aceita credenciais de usuário final da gcloud geradas usando o ID do cliente do OAuth da gcloud.
  • O Firebase Authentication exige que o ID do projeto seja fornecido na inicialização para esse tipo de credencial de usuário final.

Como solução alternativa, é possível gerar Application Default Credentials do Google na gcloud usando seu próprio ID do cliente do OAuth 2.0. O ID do cliente do OAuth precisa ser do tipo app para computador.

gcloud

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

É possível especificar o ID do projeto explicitamente na inicialização do app ou apenas usar a variável de ambiente GOOGLE_CLOUD_PROJECT. Com o último método, não é necessário fazer outras alterações para testar seu código.

Para especificar explicitamente o ID do projeto:

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óximas etapas

Saiba mais sobre o Firebase:

Adicione recursos do Firebase ao seu app: