Adicione o SDK Admin do Firebase ao seu servidor

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

  • Leia e grave dados do Realtime Database com privilégios totais de administrador.
  • Envie mensagens do Firebase Cloud Messaging de maneira programática usando uma abordagem simples e alternativa aos protocolos de servidor do Firebase Cloud Messaging.
  • Gere e verifique tokens de autenticação do Firebase.
  • Acesse recursos do Google Cloud, como buckets do Cloud Storage e bancos de dados do Cloud Firestore associados aos seus projetos do Firebase.
  • Crie seu próprio console de administração simplificado para fazer coisas como pesquisar dados do usuário ou alterar o endereço de e-mail de um usuário para autenticação.

Se você estiver interessado em usar o SDK do Node.js como cliente para acesso do usuário final (por exemplo, em um desktop Node.js ou aplicativo IoT), em vez do acesso de administrador de um ambiente privilegiado (como um servidor), você em vez disso, você deve seguir as instruções para configurar o SDK JavaScript do cliente .

Aqui está uma matriz de recursos que mostra quais recursos do Firebase são compatíveis com cada idioma:

Recurso Node.js Java Pitão Ir C#
Cunhagem de token personalizado
Verificação de token de identificação
Gerenciamento de usuários
Controle o acesso com declarações personalizadas
Atualizar revogação de token
Importar usuários
Gerenciamento de cookies de sessão
Gerando links de ação por e-mail
Gerenciando configurações do provedor SAML/OIDC
Suporte multilocatário
Banco de dados em tempo real *
Mensagens na nuvem do Firebase
Multitransmissão FCM
Gerenciar assinaturas de tópicos do FCM
Armazenamento na núvem
Cloud Firestore
Enfileirar funções com Cloud Tasks
Gerenciamento de projetos
Regras de segurança
Gerenciamento de modelo de ML
Configuração remota do Firebase
Verificação do aplicativo Firebase
Extensões do Firebase

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

Pré-requisitos

  • Certifique-se de ter um aplicativo de servidor.

  • Certifique-se de que seu servidor execute o seguinte, dependendo de qual Admin SDK você usa:

    • Admin Node.js SDK – Node.js 14+ (recomendado Node.js 16+)
      O suporte ao Node.js 14 está obsoleto.
    • Admin Java SDK – Java 8+
    • Admin Python SDK – Python 3.7+ (recomendado Python 3.8+)
      O suporte ao Python 3.7 está obsoleto.
    • SDK Admin Go – Go 1.17+
    • Admin .NET SDK — .NET Framework 4.6.1+ ou .NET Standard 2.0 para .Net Core 2.0+

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

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

  • Um projeto do Firebase.
  • Uma conta de serviço do SDK Admin do Firebase para comunicação com o Firebase. Essa conta de serviço é criada automaticamente quando você cria um projeto do Firebase ou adiciona o Firebase 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, será necessário criar um no console do Firebase . Visite Entenda os projetos do Firebase para saber mais sobre os projetos do Firebase.

Adicione o SDK

Se estiver configurando um novo projeto, você precisará instalar o SDK para o idioma de sua escolha.

Node.js

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

npm install firebase-admin --save

Para usar o módulo em seu aplicativo, require o em qualquer arquivo JavaScript:

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

Se você estiver usando ES2015, poderá import o módulo:

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

Java

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

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

Se você usar o Maven para construir seu aplicativo, poderá adicionar a seguinte dependência ao seu pom.xml :

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

Pitão

O SDK Admin 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 você pode instalar a biblioteca apenas para o usuário atual, passando o sinalizador --user :

pip install --user firebase-admin

Ir

O Go Admin SDK pode ser instalado usando o utilitário go install :

# Install the latest version:
go install firebase.google.com/go/v4@latest

# Or install a specific version:
go install firebase.google.com/go/v4@4.13.0

C#

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

Install-Package FirebaseAdmin -Version 2.4.0

Como alternativa, instale-o usando o utilitário de linha de comando dotnet :

dotnet add package FirebaseAdmin --version 2.4.0

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

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

Inicialize o SDK

Depois de criar um projeto do Firebase, você pode inicializar o SDK com Google Application Default Credentials . Como a pesquisa de credenciais padrão é totalmente automatizada em ambientes Google, sem necessidade de fornecer variáveis ​​de ambiente ou outras configurações, essa forma de inicializar o SDK é altamente recomendada para aplicativos executados em ambientes Google, como Cloud Run, App Engine e Cloud Functions.

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

Node.js

const app = initializeApp();

Java

FirebaseApp.initializeApp();

Pitão

default_app = firebase_admin.initialize_app()

Ir

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ê poderá usar o Admin SDK para realizar os seguintes tipos de tarefas:

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

Pitão

cred = credentials.RefreshToken('path/to/refreshToken.json')
default_app = firebase_admin.initialize_app(cred)

Ir

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

Inicialize o SDK em ambientes que não sejam do Google

Se você estiver trabalhando em um ambiente de servidor que não seja do Google e no qual a pesquisa de credenciais padrão não possa ser totalmente automatizada, inicialize o SDK com um arquivo de chave de 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 Firebase a partir do seu servidor de aplicativos ou ambiente confiável. Se estiver desenvolvendo código localmente ou implantando seu aplicativo localmente, você poderá usar credenciais obtidas por meio dessa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la a acessar os serviços do Firebase, você deve gerar um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada para sua conta de serviço:

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

  2. Clique em Gerar nova chave privada e confirme clicando em Gerar chave .

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

Ao autorizar por meio de uma conta de serviço, você tem duas opções para fornecer as credenciais ao seu aplicativo. Você pode definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou pode passar explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é altamente recomendada.

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 sua conta de serviço. Esta variável se aplica apenas à sua sessão atual do shell, portanto, 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"

janelas

Com 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 credenciais de conta de serviço ao testar ou executar em ambientes que não sejam do Google.

Inicialize o SDK conforme 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);

Pitão

default_app = firebase_admin.initialize_app()

Ir

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

Inicialize vários aplicativos

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

Pitão

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

Ir

// 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, você pode querer ler dados do Realtime Database de um projeto do Firebase e criar tokens personalizados para outro projeto. Ou você pode querer autenticar dois aplicativos com credenciais separadas. O SDK do Firebase permite criar vários aplicativos ao mesmo tempo, cada um com suas 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);

Pitão

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

Ir

// 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 autenticação

Se você estiver usando uma VM do Google Compute Engine com credenciais padrão do aplicativo Google para Realtime Database ou autenticação, defina também os escopos de acesso corretos . Para Realtime Database e autenticação, 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 a seguir usando 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"

Teste com credenciais de usuário final do gcloud

Ao testar o SDK Admin localmente com as credenciais padrão do aplicativo do Google obtidas executando gcloud auth application-default login , alterações adicionais são necessárias para usar o Firebase Authentication devido ao seguinte:

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

Como solução alternativa, você pode gerar credenciais padrão do aplicativo Google no gcloud usando seu próprio ID de cliente OAuth 2.0 . O ID do cliente OAuth deve ser um tipo de aplicativo de desktop .

gcloud

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

Você pode especificar explicitamente o ID do projeto na inicialização do aplicativo ou apenas usar a variável de ambiente GOOGLE_CLOUD_PROJECT . Este último evita a necessidade de fazer alterações adicionais 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);

Pitão

app_options = {'projectId': '<FIREBASE_PROJECT_ID>'}
default_app = firebase_admin.initialize_app(options=app_options)

Ir

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 passos

Saiba mais sobre o Firebase:

Adicione recursos do Firebase ao seu aplicativo: