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 multitenancy

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 da 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 do projeto padrão no 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 do 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 onUserCreated, você pode configurar onUserDeleted com opções como { tenantId: IS_NOT_TENANT } para restringir 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.

As funções de bloqueio permitem que você execute 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, siga estas 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 mutável global entre execuções simultâneas.
  • Projetar para idempotência: a entrega de eventos na 2ª geração é do tipo "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 de 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.