Gatilhos do Firebase Authentication

É possível acionar as funções em resposta à criação e exclusão de contas de usuários do Firebase Authentication. Por exemplo, você pode enviar um e-mail de apresentação para um usuário que acabou de criar uma conta no seu app. Os exemplos nesta página são baseados em uma amostra que faz exatamente isso: envia e-mails de apresentação e de despedida após a criação e exclusão de contas.

Para mais exemplos de casos de uso, acesse O que posso fazer com o Cloud Functions?.

Acionar uma função na criação do usuário

É possível criar uma função que será acionada quando um usuário do Authentication for criado usando o manipulador de eventos onUserCreated do subpacote firebase-functions/v2/identity:

const { onUserCreated } = require("firebase-functions/identity");
const { defineSecret } = require("firebase-functions/params");
const { logger } = require("firebase-functions");
const { sendWelcomeEmail } = require("./utils/myEmailService");

const emailApiKey = defineSecret("EMAIL_API_KEY");

exports.newUserWelcome = onUserCreated(
  { secrets: [emailApiKey] },
  async (event) => {
    const { uid, email, displayName } = event.data;

    if (!email) {
      logger.log(`User ${uid} does not have an email address.`);
      return;
    }

    await sendWelcomeEmail(email, displayName);
  },
);

As contas Authentication acionam eventos de criação de usuários para o Cloud Functions quando:

  • um usuário criar uma conta de e-mail e uma senha;
  • um usuário fizer login pela primeira vez com um provedor de identidade federado;
  • o desenvolvedor criar uma conta usando o SDK Admin;
  • um usuário fizer login em uma sessão de autenticação anônima pela primeira vez.

Um evento do Cloud Functions não é ativado quando um usuário faz login pela primeira vez usando um token personalizado.

Configurar opções de gatilho e multilocação

Para configurar a função, transmita um objeto de opções (AuthOptions) como o primeiro parâmetro para onUserCreated:

/**
 * Sends a welcome email scoped to a specific tenant in Identity Platform.
 */
exports.sendWelcomeEmailToTenant = onUserCreated(
  {
    secrets: [emailApiKey],
    // Only trigger when a user is a member of this tenant
    tenantId: "my-tenant-id",
  },
  async (event) => {
    const { uid, email, displayName } = event.data;
    // Customize the email for this tenant
    await sendWelcomeEmail(email, displayName, event.tenantId);
  },
);
  /**
 * Sends a welcome email only to users not associated with any tenant.
 */
exports.sendWelcomeEmailNoTenant = onUserCreated(
  {
    secrets: [emailApiKey],
    // Only trigger when a user is NOT a member of a tenant
    tenantId: IS_NOT_TENANT,
  },
  async (event) => {
    const { email, displayName } = event.data;

    // Send a generic welcome email
    await sendWelcomeEmail(email, displayName);
  },
);

Se o projeto usar a multilocação do Identity Platform, é possível definir o escopo do gatilho:

  • Projeto padrão (sem locatário): defina tenantId como IS_NOT_TENANT para ouvir apenas os usuários criados no projeto padrão.
  • Locatário específico: forneça o ID de string do locatário (por exemplo, { tenantId: "tenant-id-1" }) para ouvir apenas os usuários criados nesse locatário.
  • Todos os locatários e usuários: se tenantId for omitido, a função será acionada em eventos de criação de usuários em todos os locatários e usuários padrão do projeto.

Além de tenantId, é possível especificar opções de configuração padrão da 2ª geração, incluindo region, concurrency, cpu, memory, timeoutSeconds, minInstances, maxInstances e secrets.

Acessar os atributos do usuário

Com os dados do usuário retornados para sua função, você pode acessar a lista de atributos dele disponíveis no objeto UserRecord recém-criado via event.data. Por exemplo, é possível ver o e-mail e o nome de exibição do usuário conforme mostrado abaixo:

const { uid, email, displayName } = event.data;

Os gatilhos de autenticação na 2ª geração recebem um objeto AuthEvent. Além de event.data, é possível acessar metadados de eventos, como:

  • event.id: um identificador exclusivo do evento.
  • event.type: o tipo de evento (google.firebase.auth.user.v2.created).
  • event.time: um carimbo de data/hora ISO 8601 que representa quando o evento ocorreu.
  • event.project: o ID do projeto do Google Cloud.
  • event.tenantId: o ID do locatário da Identity Platform associado ao usuário, se aplicável.

Acionar uma função na exclusão do usuário

Além de acionar uma função na criação do usuário, você pode responder a eventos de exclusão de usuários. Use o manipulador de eventos onUserDeleted de firebase-functions/v2/identity conforme mostrado:

const { onUserDeleted } = require("firebase-functions/identity");
const { defineSecret } = require("firebase-functions/params");
const { logger } = require("firebase-functions");
const { sendGoodbyeEmail } = require("./utils/myEmailService");

const emailApiKey = defineSecret("EMAIL_API_KEY");

exports.deletedUserFarewell = onUserDeleted(
  { secrets: [emailApiKey] },
  async (event) => {
    const { uid, email, displayName } = event.data;
    if (!email) {
      logger.log(`User ${uid} does not have an email address.`);
      return;
    }

    await sendGoodbyeEmail(email, displayName);
  },
);

Assim como no onUserCreated, é possível configurar o onUserDeleted com opções como { tenantId: IS_NOT_TENANT } para restringir os acionadores a usuários no projeto padrão.

Acionar funções de bloqueio

Se você fez upgrade para o Firebase Authentication with Identity Platform, é possível estender o Firebase Authentication usando funções de bloqueio.

Com as funções de bloqueio, é possível executar um código personalizado de forma síncrona que modifica o resultado de um usuário se registrando ou fazendo login no app. Ao contrário dos gatilhos em segundo plano, que são executados de forma assíncrona após a conclusão de um evento, as funções de bloqueio permitem impedir que um usuário faça a autenticação caso não atenda a determinados critérios ou atualizar as informações e declarações de um usuário antes de retornar esses dados ao app cliente.

Práticas recomendadas para acionadores de 2ª geração

Ao implementar gatilhos de autenticação de 2ª geração, lembre-se das seguintes práticas recomendadas:

  • Considere a simultaneidade: as instâncias do Cloud Functions (2ª geração) processam solicitações simultâneas (o padrão é 80 solicitações simultâneas quando a CPU é ≥ 1). Verifique se a função não depende de um estado global mutável entre execuções simultâneas.
  • Projetar para idempotência: a entrega de eventos na 2ª geração é de pelo menos uma vez via Eventarc. Verifique se as funções são idempotentes. Por exemplo, confira se um e-mail de boas-vindas já foi enviado ou se uma entrada de banco de dados foi inicializada antes de realizar efeitos colaterais.
  • Escopo das funções multilocatárias: se o aplicativo usar a multilocação do Identity Platform, verifique se as funções precisam processar eventos em todos os locatários ou apenas em alguns específicos. Use tenantId: IS_NOT_TENANT para impedir que usuários do locatário acionem funções destinadas apenas ao projeto principal.
  • Gerenciar regiões e alocação de recursos: especifique o local da função (region) para minimizar a latência de rede entre o provedor de autenticação e o ambiente de execução da função.