Como instalar o SDK Admin

Veja neste documento como instalar o SDK Admin do Identity Platform. Com o SDK Admin, você gerencia o Identity Platform de um ambiente de servidor e realiza ações de administrador, como migrar usuários, definir declarações personalizadas e configurar provedores de identidade.

Antes de começar

Para usar o SDK Admin, você precisa de um app de servidor que execute um dos seguintes procedimentos:

Idioma Versão mínima do framework
Node.js Node.js 8.13.0+
Java Java 7+ (Java 8+ recomendado)
Python Python 2.7+ ou 3.4+ (3.4+ recomendado)
Go Go 1.9+
C# .NET Framework 4.5+ ou .NET Core 1.5+

A tabela a seguir lista os recursos compatíveis com cada linguagem de SDK:

Feature Node.js Java Python Go C#
Emissão de tokens personalizada
Como verificar tokens de ID
Gerenciamento de usuários
Como controlar o acesso com declarações personalizadas
Como revogar tokens de atualização
Como importar usuários
Como gerenciar cookies de sessão
Como gerar links de ação de e-mail
Como gerenciar configurações de provedores de SAML e OIDC
Suporte a multilocação

Além disso, você precisará de uma conta de serviço e uma chave para seu projeto:

Console do Cloud

Crie uma conta de serviço:

  1. No Console do Cloud, acesse a página Criar conta de serviço.

    Acesse Criar conta de serviço
  2. Selecione um projeto.
  3. No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.

    No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

  4. Clique em Criar e continuar.
  5. Clique no campo Selecionar um papel.

    Em Acesso rápido, clique em Básico e em Proprietário.

  6. Clique em Continuar.
  7. Clique em Concluído para terminar a criação da conta de serviço.

    Não feche a janela do navegador. Você vai usá-lo na próxima etapa.

Crie uma chave de conta de serviço:

  1. No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
  2. Clique em Chaves.
  3. Clique em Adicionar chave e em Criar nova chave.
  4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
  5. Clique em Fechar.

Linha de comando

É possível executar os seguintes comandos usando o SDK do Cloud na máquina local ou no Cloud Shell.

  1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

    gcloud iam service-accounts create NAME
  2. Conceda permissões à conta de serviço. Substitua PROJECT_ID pelo ID do seu projeto.

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"
  3. Gere o arquivo de chave. Substitua FILE_NAME pelo nome do arquivo de chave.

    gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com

Forneça credenciais de autenticação ao código do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Essa variável só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Exemplo:

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

Windows

Para PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Exemplo:

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

Para prompt de comando:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Installing the SDK

Node.js

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

npm install firebase-admin --save

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

var admin = require('firebase-admin');

Se você estiver usando ES2015, use import no módulo:

import * as admin from 'firebase-admin';

Java

O SDK Admin para Java é 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:6.11.0'
}

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

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

Python

O SDK Admin para Python está disponível usando pip.

pip install --user firebase-admin

Go

Use o utilitário go get para instalar o SDK Admin do Go:

go get firebase.google.com/go

C#

Instale o SDK Admin do .NET usando o gerenciador de pacotes .NET:

Install-Package FirebaseAdmin -Version 1.9.1

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

dotnet add package FirebaseAdmin --version 1.9.1

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

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

Como inicializar o SDK usando credenciais padrão

Adicione o seguinte código ao app de servidor para inicializar o SDK Admin usando as credenciais padrão:

Node.js

// Initialize the default app
var admin = require('firebase-admin');
var app = admin.initializeApp({
  credential: admin.credential.applicationDefault()
});

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

Como inicializar o SDK com um arquivo de chave da conta de serviço

Também é possível especificar manualmente um arquivo de chave da conta de serviço:

Node.js

// Initialize the default app
var admin = require('firebase-admin');
var app = admin.initializeApp({
  credential: admin.credential.cert('/path/to/serviceAccountKey.json')
});

Java

FileInputStream serviceAccount = new FileInputStream("path/to/serviceAccountKey.json");

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

import firebase_admin
from firebase_admin import credentials
from firebase_admin import exceptions

cred = credentials.Certificate('path/to/serviceAccountKey.json')
default_app = firebase_admin.initialize_app(cred)

Go

opt := option.WithCredentialsFile("path/to/serviceAccountKey.json")
app, err := firebase.NewApp(context.Background(), nil, opt)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.FromFile("path/to/serviceAccountKey.json"),
});

Como inicializar vários aplicativos

Normalmente, você só precisará inicializar um único app padrão. No entanto, também é possível criar várias instâncias de aplicativos, cada uma com as próprias opções de configuração e estado de autenticação.

Node.js

// Initialize the default app
admin.initializeApp(defaultAppConfig);

// Initialize another app with a different config
var otherApp = admin.initializeApp(otherAppConfig, 'other');

console.log(admin.app().name);  // '[DEFAULT]'
console.log(otherApp.name);     // 'other'

// Use the shorthand notation to retrieve the default app's services
var defaultAuth = admin.auth();

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

Como definir escopos

Se estiver usando uma VM do Compute Engine com o Application Default Credentials do Google para autenticação, você precisará definir os escopos de acesso corretos. O Identity Platform requer os escopos de acesso userinfo.email e cloud-platform.

Para verificar os escopos de acesso atuais, execute o comando a seguir:

gcloud compute instances describe [INSTANCE-NAME] --format json

O comando retornará informações sobre a conta de serviço. Exemplo:

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

Para atualizar os escopos de acesso, interrompa a VM e execute o seguinte:


gcloud compute instances set-service-account [INSTANCE-NAME] \
  --service-account "your.gserviceaccount.com" \
  --scopes ""https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email"

A seguir