Firebase Authentication-Trigger

Sie können Funktionen als Reaktion auf das Erstellen und Löschen von Firebase Authentication-Nutzerkonten auslösen. Sie haben beispielsweise die Möglichkeit, eine Begrüßungs-E-Mail an einen Nutzer zu senden, der gerade ein Konto in Ihrer Anwendung erstellt hat. Die Beispiele auf dieser Seite basieren auf einem Beispiel für genau diesen Anwendungsfall: das Versenden von Begrüßungs- und Abschieds-E-Mails beim Erstellen und Löschen von Konten.

Weitere Beispiele für Anwendungsfälle finden Sie unter Was kann ich mit Cloud Functions tun?.

Funktion beim Erstellen eines Nutzers auslösen

Sie können eine Funktion erstellen, die ausgelöst wird, wenn ein Authentication-Nutzer mit dem Ereignis-Handler onUserCreated aus dem Unterpaket firebase-functions/v2/identity erstellt wird:

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

Authentication-Konten lösen in den folgenden Fällen Nutzererstellungsereignisse für Cloud Functions aus:

  • Ein Nutzer erstellt ein E-Mail-Konto und ein Passwort
  • Ein Nutzer meldet sich zum ersten Mal über einen Anbieter föderierter Identitäten an.
  • Der Entwickler erstellt mithilfe des Admin SDK ein Konto.
  • Ein Nutzer meldet sich zum ersten Mal bei einer neuen anonymen Authentifizierungssitzung an.

Ein Cloud Functions-Ereignis wird nicht ausgelöst, wenn sich ein Nutzer zum ersten Mal über ein benutzerdefiniertes Token anmeldet.

Triggeroptionen und Mandantenfähigkeit konfigurieren

Sie können Ihre Funktion konfigurieren, indem Sie ein Optionenobjekt (AuthOptions) als ersten Parameter an onUserCreated übergeben:

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

Wenn in Ihrem Projekt die Mehrinstanzenfähigkeit von Identity Platform verwendet wird, können Sie den Trigger eingrenzen:

  • Standardprojekt (kein Mandant): Legen Sie tenantId auf IS_NOT_TENANT fest, um nur auf Nutzer zu warten, die im Standardprojekt erstellt wurden.
  • Bestimmter Mandant: Geben Sie die String-ID des Mandanten an (z. B. { tenantId: "tenant-id-1" }), um nur auf Nutzer zu warten, die in diesem Mandanten erstellt wurden.
  • Alle Mandanten und Nutzer: Wenn tenantId weggelassen wird, wird die Funktion bei Ereignissen zum Erstellen von Nutzern in allen Mandanten und Standardprojekt-Nutzern im Projekt ausgelöst.

Zusätzlich zu tenantId können Sie Standardkonfigurationsoptionen der 2. Generation angeben, darunter region, concurrency, cpu, memory, timeoutSeconds, minInstances, maxInstances und secrets.

Auf Nutzerattribute zugreifen

Über die Nutzerdaten, die an die Funktion zurückgegeben werden, können Sie über event.data auf die Liste der Nutzerattribute zugreifen, die im Objekt UserRecord des neu erstellten Nutzers verfügbar sind. So können Sie beispielsweise die E-Mail-Adresse und den Anzeigenamen des Nutzers abrufen:

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

Authentifizierungstrigger in der 2. Generation erhalten ein AuthEvent-Objekt. Zusätzlich zu event.data können Sie auf Ereignismetadaten wie die folgenden zugreifen:

  • event.id: Eine eindeutige Kennung für das Ereignis.
  • event.type: Der Ereignistyp (google.firebase.auth.user.v2.created).
  • event.time: Ein ISO 8601-Zeitstempel, der angibt, wann das Ereignis stattgefunden hat.
  • event.project: die Google Cloud-Projekt-ID.
  • event.tenantId: Die Identity Platform-Mandanten-ID, die dem Nutzer zugeordnet ist, falls zutreffend.

Funktion beim Löschen eines Nutzers auslösen

So wie sich eine Funktion beim Erstellen von Nutzern auslösen lässt, können Sie auf Ereignisse beim Löschen von Nutzern reagieren. Verwenden Sie dazu den Ereignis-Handler onUserDeleted aus firebase-functions/v2/identity, wie hier gezeigt:

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

Wie bei onUserCreated können Sie onUserDeleted mit Optionen wie { tenantId: IS_NOT_TENANT } konfigurieren, um Trigger auf Nutzer im Standardprojekt zu beschränken.

Blockierfunktionen auslösen

Wenn Sie ein Upgrade auf Firebase Authentication with Identity Platform durchgeführt haben, können Sie Firebase Authentication mit Blockierfunktionen erweitern.

Mit Blockierfunktionen können Sie benutzerdefinierten Code synchron ausführen, der das Ergebnis einer Nutzerregistrierung oder Anmeldung bei Ihrer App ändert. Im Gegensatz zu Hintergrund-Triggern, die asynchron nach Abschluss eines Ereignisses ausgeführt werden, können Sie mit Blockierfunktionen verhindern, dass ein Nutzer sich authentifizieren kann, wenn er bestimmte Kriterien nicht erfüllt. Außerdem können Sie die Informationen und Ansprüche eines Nutzers aktualisieren, bevor sie an Ihre Client-App zurückgegeben werden.

Best Practices für Trigger der 2. Generation

Beachten Sie beim Implementieren von Authentifizierungstriggern der 2. Generation die folgenden Best Practices:

  • Nebenläufigkeit berücksichtigen: Cloud Functions (2. Generation)-Instanzen verarbeiten gleichzeitige Anfragen (standardmäßig 80 gleichzeitige Anfragen, wenn CPU ≥ 1). Achten Sie darauf, dass Ihre Funktion bei gleichzeitigen Ausführungen nicht auf globalen veränderlichen Zustand angewiesen ist.
  • Idempotenz berücksichtigen: Die Ereignisübermittlung in der 2. Generation erfolgt mindestens einmal über Eventarc. Achten Sie darauf, dass Ihre Funktionen idempotent sind. Prüfen Sie beispielsweise, ob eine Begrüßungs-E-Mail bereits gesendet oder ein Datenbankeintrag initialisiert wurde, bevor Sie Nebeneffekte ausführen.
  • Funktionen für mehrere Mandanten eingrenzen: Wenn Ihre Anwendung die Mehrinstanzenfähigkeit von Identity Platform verwendet, prüfen Sie, ob Ihre Funktionen Ereignisse für alle oder nur für bestimmte Mandanten verarbeiten sollen. Verwenden Sie tenantId: IS_NOT_TENANT, um zu verhindern, dass Mandantenfunktionen ausgelöst werden, die nur für das primäre Projekt vorgesehen sind.
  • Regionen und Ressourcenzuweisung verwalten: Geben Sie den Funktionsstandort (region) an, um die Netzwerklatenz zwischen Ihrem Authentifizierungsanbieter und der Umgebung, in der die Funktion ausgeführt wird, zu minimieren.