Criar tokens personalizados

Este documento mostra como usar a Identity Platform para criar símbolos da Web JSON (JWTs) personalizados.

Os tokens personalizados dão-lhe controlo total sobre o processo de autenticação. Gera estes tokens no seu servidor, transmite-os de volta para um dispositivo cliente e, em seguida, chama signInWithCustomToken() para iniciar sessão nos utilizadores.

Pode criar tokens personalizados com o SDK de administrador da Identity Platform ou usar uma biblioteca JWT de terceiros.

Antes de começar

  • Instale o SDK Admin. Se estiver a usar a deteção automática de contas de serviço ou um ID de conta de serviço especificado explicitamente, certifique-se de que a conta de serviço que está a usar tem, pelo menos, a função Criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator).

  • Crie e implemente um ponto final do servidor que aceite credenciais de início de sessão de utilizadores.

Criar tokens personalizados com o SDK de administração

O SDK de administrador tem um método incorporado para criar tokens personalizados. No mínimo, tem de indicar um uid. Pode ser qualquer string que identifique o utilizador ou o dispositivo de forma única. Estes tokens expiram após uma hora.

O exemplo seguinte mostra como criar um token personalizado:

Node.js

const uid = 'some-uid';

getAuth()
  .createCustomToken(uid)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
create_custom_tokens.js

Java

String uid = "some-uid";

String customToken = FirebaseAuth.getInstance().createCustomToken(uid);
// Send token back to client
FirebaseAuthSnippets.java

Python

uid = 'some-uid'

custom_token = auth.create_custom_token(uid)
index.py

Ir

client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

token, err := client.CustomToken(ctx, "some-uid")
if err != nil {
	log.Fatalf("error minting custom token: %v\n", err)
}

log.Printf("Got custom token: %v\n", token)
auth.go

C#

var uid = "some-uid";

string customToken = await FirebaseAuth.DefaultInstance.CreateCustomTokenAsync(uid);
// Send token back to client
FirebaseAuthSnippets.cs

Depois de criar um token personalizado, a sua app pode usá-lo para iniciar sessão de um utilizador.

Opcionalmente, pode incluir reivindicações adicionais no token personalizado. Estas são propagadas para o token de ID do utilizador como reivindicações de nível superior.

O exemplo seguinte mostra como adicionar uma reivindicação premiumAccount:

Node.js

const userId = 'some-uid';
const additionalClaims = {
  premiumAccount: true,
};

getAuth()
  .createCustomToken(userId, additionalClaims)
  .then((customToken) => {
    // Send token back to client
  })
  .catch((error) => {
    console.log('Error creating custom token:', error);
  });
create_custom_tokens.js

Java

String uid = "some-uid";
Map<String, Object> additionalClaims = new HashMap<String, Object>();
additionalClaims.put("premiumAccount", true);

String customToken = FirebaseAuth.getInstance()
    .createCustomToken(uid, additionalClaims);
// Send token back to client
FirebaseAuthSnippets.java

Python

uid = 'some-uid'
additional_claims = {
    'premiumAccount': True
}

custom_token = auth.create_custom_token(uid, additional_claims)
index.py

Ir

client, err := app.Auth(context.Background())
if err != nil {
	log.Fatalf("error getting Auth client: %v\n", err)
}

claims := map[string]interface{}{
	"premiumAccount": true,
}

token, err := client.CustomTokenWithClaims(ctx, "some-uid", claims)
if err != nil {
	log.Fatalf("error minting custom token: %v\n", err)
}

log.Printf("Got custom token: %v\n", token)
auth.go

C#

var uid = "some-uid";
var additionalClaims = new Dictionary<string, object>()
{
    { "premiumAccount", true },
};

string customToken = await FirebaseAuth.DefaultInstance
    .CreateCustomTokenAsync(uid, additionalClaims);
// Send token back to client
FirebaseAuthSnippets.cs

O Identity Platform está em conformidade com a especificação JWT do OpenID Connect. Isto significa que as seguintes reivindicações estão reservadas e não podem ser especificadas:

  • acr
  • amr
  • at_hash
  • aud
  • auth_time
  • azp
  • cnf
  • c_hash
  • exp
  • firebase
  • iat
  • iss
  • jti
  • nbf
  • nonce
  • sub

Criar tokens personalizados com uma biblioteca JWT de terceiros

Se o seu back-end estiver escrito num idioma que o SDK Admin não suporta, pode continuar a criar manualmente tokens personalizados. Primeiro, encontre uma biblioteca JWT de terceiros para o seu idioma. Em seguida, use essa biblioteca para gerar um JWT que inclua as seguintes reivindicações:

alg Algoritmo "RS256"
iss Emissor O endereço de email da conta de serviço do seu projeto.
sub Assunto O endereço de email da conta de serviço do seu projeto.
aud Público-alvo "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
iat Hora de emissão A hora atual, em segundos, desde o início da época UNIX.
exp Período de validade A hora, em segundos desde o início da época UNIX, em que o token expira. Pode ser, no máximo, 3600 segundos depois da iat.
Tenha em atenção que isto só controla a hora em que o token personalizado expira. Depois de iniciar sessão de um utilizador com signInWithCustomToken(), a sessão permanece iniciada até que o utilizador termine sessão ou a sessão seja invalidada.
uid O identificador exclusivo do utilizador com sessão iniciada. Tem de ser uma string com um comprimento de 1 a 36 carateres.
claims (opcional) Reivindicações personalizadas adicionais a incluir.

Os exemplos seguintes demonstram como criar tokens personalizados em idiomas que o SDK Admin não suporta:

PHP

Usar php-jwt:

// Requires: composer require firebase/php-jwt
use Firebase\JWT\JWT;

// Get your service account's email address and private key from the JSON key file
$service_account_email = "abc-123@a-b-c-123.iam.gserviceaccount.com";
$private_key = "-----BEGIN PRIVATE KEY-----...";

function create_custom_token($uid, $is_premium_account) {
  global $service_account_email, $private_key;

  $now_seconds = time();
  $payload = array(
  "iss" => $service_account_email,
  "sub" => $service_account_email,
  "aud" => "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit",
  "iat" => $now_seconds,
  "exp" => $now_seconds+(60*60),  // Maximum expiration time is one hour
  "uid" => $uid,
  "claims" => array(
      "premium_account" => $is_premium_account
  )
  );
  return JWT::encode($payload, $private_key, "RS256");
}

Ruby

Usar ruby-jwt:

require "jwt"

# Get your service account's email address and private key from the JSON key file
$service_account_email = "service-account@my-project-abc123.iam.gserviceaccount.com"
$private_key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."

def create_custom_token(uid, is_premium_account)
  now_seconds = Time.now.to_i
  payload = {:iss => $service_account_email,
              :sub => $service_account_email,
              :aud => "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit",
              :iat => now_seconds,
              :exp => now_seconds+(60*60), # Maximum expiration time is one hour
              :uid => uid,
              :claims => {:premium_account => is_premium_account}}
  JWT.encode payload, $private_key, "RS256"
end

Depois de criar um token personalizado, a sua app pode usá-lo para iniciar sessão de um utilizador.

O que se segue?