Erstellen Sie benutzerdefinierte E-Mail-Aktionshandler

Einige Benutzerverwaltungsaktionen, wie das Aktualisieren der E-Mail-Adresse eines Benutzers und das Zurücksetzen des Passworts eines Benutzers, führen dazu, dass E-Mails an den Benutzer gesendet werden. Diese E-Mails enthalten Links, die Empfänger öffnen können, um die Benutzerverwaltungsaktion abzuschließen oder abzubrechen. Standardmäßig sind E-Mails zur Benutzerverwaltung mit dem Standard-Aktionshandler verknüpft, einer Webseite, die unter einer URL in der Firebase-Hosting-Domäne Ihres Projekts gehostet wird.

Sie können stattdessen einen benutzerdefinierten E-Mail-Aktionshandler erstellen und hosten, um eine benutzerdefinierte Verarbeitung durchzuführen und den E-Mail-Aktionshandler in Ihre Website zu integrieren.

Die folgenden Benutzerverwaltungsaktionen erfordern, dass der Benutzer die Aktion mithilfe eines E-Mail-Aktionshandlers abschließt:

  • Passwörter zurücksetzen
  • Änderungen an E-Mail-Adressen widerrufen: Wenn Benutzer die primären E-Mail-Adressen ihrer Konten ändern, sendet Firebase eine E-Mail an ihre alten Adressen, die es ihnen ermöglicht, die Änderung rückgängig zu machen
  • E-Mail-Adressen überprüfen

Um den E-Mail-Aktionshandler Ihres Firebase-Projekts anzupassen, müssen Sie eine Webseite erstellen und hosten, die das Firebase JavaScript SDK verwendet, um die Gültigkeit der Anfrage zu überprüfen und die Anfrage abzuschließen. Anschließend müssen Sie die E-Mail-Vorlagen Ihres Firebase-Projekts anpassen, um eine Verknüpfung zu Ihrem benutzerdefinierten Aktionshandler herzustellen.

Erstellen Sie die E-Mail-Aktionshandlerseite

  1. Firebase fügt Ihrer Aktionshandler-URL mehrere Abfrageparameter hinzu, wenn E-Mails zur Benutzerverwaltung generiert werden. Beispiel:

    https://example.com/usermgmt?mode=resetPassword&oobCode=ABC123&apiKey=AIzaSy...&lang=fr

    Diese Parameter geben die Benutzerverwaltungsaufgabe an, die der Benutzer ausführt. Ihre E-Mail-Aktionshandlerseite muss die folgenden Abfrageparameter verarbeiten:

    Parameter
    Modus

    Die auszuführende Benutzerverwaltungsaktion. Kann einer der folgenden Werte sein:

    • resetPassword
    • recoverEmail
    • verifyEmail
    oobCode Ein einmaliger Code, der zur Identifizierung und Verifizierung einer Anfrage verwendet wird
    API-Schlüssel Der API-Schlüssel Ihres Firebase-Projekts, der der Einfachheit halber bereitgestellt wird
    continueUrl Dies ist eine optionale URL, die eine Möglichkeit bietet, den Status über eine URL an die App zurückzugeben. Dies ist relevant für die Modi zum Zurücksetzen des Passworts und zur E-Mail-Verifizierung. Beim Senden einer E-Mail zum Zurücksetzen des Passworts oder einer Bestätigungs-E-Mail muss ein ActionCodeSettings Objekt mit einer Fortsetzungs-URL angegeben werden, damit dieses verfügbar ist. Dies ermöglicht es einem Benutzer, nach einer E-Mail-Aktion genau dort fortzufahren, wo er aufgehört hat.
    lang

    Dies ist das optionale BCP47- Sprachtag, das das Gebietsschema des Benutzers darstellt (z. fr ). Sie können diesen Wert verwenden, um Ihren Benutzern lokalisierte E-Mail-Aktionshandlerseiten bereitzustellen.

    Die Lokalisierung kann über die Firebase-Konsole oder dynamisch durch Aufruf der entsprechenden Client-API vor dem Auslösen der E-Mail-Aktion festgelegt werden. Beispielsweise mit JavaScript: firebase.auth().languageCode = 'fr'; .

    Stellen Sie für eine konsistente Benutzererfahrung sicher, dass die Lokalisierung des E-Mail-Aktionshandlers mit der der E-Mail-Vorlage übereinstimmt.

    Das folgende Beispiel zeigt, wie Sie die Abfrageparameter in einem browserbasierten Handler verarbeiten könnten. (Mit ähnlicher Logik können Sie den Handler auch als Node.js-Anwendung implementieren.)

    Web modular API

    import { initializeApp } from "firebase/app";
    import { getAuth } from "firebase/auth";
    
    document.addEventListener('DOMContentLoaded', () => {
      // TODO: Implement getParameterByName()
    
      // Get the action to complete.
      const mode = getParameterByName('mode');
      // Get the one-time code from the query parameter.
      const actionCode = getParameterByName('oobCode');
      // (Optional) Get the continue URL from the query parameter if available.
      const continueUrl = getParameterByName('continueUrl');
      // (Optional) Get the language code if available.
      const lang = getParameterByName('lang') || 'en';
    
      // Configure the Firebase SDK.
      // This is the minimum configuration required for the API to be used.
      const config = {
        'apiKey': "YOUR_API_KEY" // Copy this key from the web initialization
                                 // snippet found in the Firebase console.
      };
      const app = initializeApp(config);
      const auth = getAuth(app);
    
      // Handle the user management action.
      switch (mode) {
        case 'resetPassword':
          // Display reset password handler and UI.
          handleResetPassword(auth, actionCode, continueUrl, lang);
          break;
        case 'recoverEmail':
          // Display email recovery handler and UI.
          handleRecoverEmail(auth, actionCode, lang);
          break;
        case 'verifyEmail':
          // Display email verification handler and UI.
          handleVerifyEmail(auth, actionCode, continueUrl, lang);
          break;
        default:
          // Error: invalid mode.
      }
    }, false);

    Web namespaced API

    document.addEventListener('DOMContentLoaded', () => {
      // TODO: Implement getParameterByName()
    
      // Get the action to complete.
      var mode = getParameterByName('mode');
      // Get the one-time code from the query parameter.
      var actionCode = getParameterByName('oobCode');
      // (Optional) Get the continue URL from the query parameter if available.
      var continueUrl = getParameterByName('continueUrl');
      // (Optional) Get the language code if available.
      var lang = getParameterByName('lang') || 'en';
    
      // Configure the Firebase SDK.
      // This is the minimum configuration required for the API to be used.
      var config = {
        'apiKey': "YOU_API_KEY" // Copy this key from the web initialization
                                // snippet found in the Firebase console.
      };
      var app = firebase.initializeApp(config);
      var auth = app.auth();
    
      // Handle the user management action.
      switch (mode) {
        case 'resetPassword':
          // Display reset password handler and UI.
          handleResetPassword(auth, actionCode, continueUrl, lang);
          break;
        case 'recoverEmail':
          // Display email recovery handler and UI.
          handleRecoverEmail(auth, actionCode, lang);
          break;
        case 'verifyEmail':
          // Display email verification handler and UI.
          handleVerifyEmail(auth, actionCode, continueUrl, lang);
          break;
        default:
          // Error: invalid mode.
      }
    }, false);
  2. Behandeln Sie Anfragen zum Zurücksetzen von Passwörtern, indem Sie zunächst den Aktionscode mit verifyPasswordResetCode überprüfen. Holen Sie sich dann ein neues Passwort vom Benutzer und übergeben Sie es an confirmPasswordReset . Zum Beispiel:

    Web modular API

    import { verifyPasswordResetCode, confirmPasswordReset } from "firebase/auth";
    
    function handleResetPassword(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
    
      // Verify the password reset code is valid.
      verifyPasswordResetCode(auth, actionCode).then((email) => {
        const accountEmail = email;
    
        // TODO: Show the reset screen with the user's email and ask the user for
        // the new password.
        const newPassword = "...";
    
        // Save the new password.
        confirmPasswordReset(auth, actionCode, newPassword).then((resp) => {
          // Password reset has been confirmed and new password updated.
    
          // TODO: Display a link back to the app, or sign-in the user directly
          // if the page belongs to the same domain as the app:
          // auth.signInWithEmailAndPassword(accountEmail, newPassword);
    
          // TODO: If a continue URL is available, display a button which on
          // click redirects the user back to the app via continueUrl with
          // additional state determined from that URL's parameters.
        }).catch((error) => {
          // Error occurred during confirmation. The code might have expired or the
          // password is too weak.
        });
      }).catch((error) => {
        // Invalid or expired action code. Ask user to try to reset the password
        // again.
      });
    }

    Web namespaced API

    function handleResetPassword(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
    
      // Verify the password reset code is valid.
      auth.verifyPasswordResetCode(actionCode).then((email) => {
        var accountEmail = email;
    
        // TODO: Show the reset screen with the user's email and ask the user for
        // the new password.
        var newPassword = "...";
    
        // Save the new password.
        auth.confirmPasswordReset(actionCode, newPassword).then((resp) => {
          // Password reset has been confirmed and new password updated.
    
          // TODO: Display a link back to the app, or sign-in the user directly
          // if the page belongs to the same domain as the app:
          // auth.signInWithEmailAndPassword(accountEmail, newPassword);
    
          // TODO: If a continue URL is available, display a button which on
          // click redirects the user back to the app via continueUrl with
          // additional state determined from that URL's parameters.
        }).catch((error) => {
          // Error occurred during confirmation. The code might have expired or the
          // password is too weak.
        });
      }).catch((error) => {
        // Invalid or expired action code. Ask user to try to reset the password
        // again.
      });
    }
  3. Behandeln Sie den Widerruf von E-Mail-Adressänderungen, indem Sie zunächst den Aktionscode mit checkActionCode überprüfen. Stellen Sie dann die E-Mail-Adresse des Benutzers mit applyActionCode wieder her. Zum Beispiel:

    Web modular API

    import { checkActionCode, applyActionCode, sendPasswordResetEmail } from "firebase/auth";
    
    function handleRecoverEmail(auth, actionCode, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      let restoredEmail = null;
      // Confirm the action code is valid.
      checkActionCode(auth, actionCode).then((info) => {
        // Get the restored email address.
        restoredEmail = info['data']['email'];
    
        // Revert to the old email.
        return applyActionCode(auth, actionCode);
      }).then(() => {
        // Account email reverted to restoredEmail
    
        // TODO: Display a confirmation message to the user.
    
        // You might also want to give the user the option to reset their password
        // in case the account was compromised:
        sendPasswordResetEmail(auth, restoredEmail).then(() => {
          // Password reset confirmation sent. Ask user to check their email.
        }).catch((error) => {
          // Error encountered while sending password reset code.
        });
      }).catch((error) => {
        // Invalid code.
      });
    }

    Web namespaced API

    function handleRecoverEmail(auth, actionCode, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      var restoredEmail = null;
      // Confirm the action code is valid.
      auth.checkActionCode(actionCode).then((info) => {
        // Get the restored email address.
        restoredEmail = info['data']['email'];
    
        // Revert to the old email.
        return auth.applyActionCode(actionCode);
      }).then(() => {
        // Account email reverted to restoredEmail
    
        // TODO: Display a confirmation message to the user.
    
        // You might also want to give the user the option to reset their password
        // in case the account was compromised:
        auth.sendPasswordResetEmail(restoredEmail).then(() => {
          // Password reset confirmation sent. Ask user to check their email.
        }).catch((error) => {
          // Error encountered while sending password reset code.
        });
      }).catch((error) => {
        // Invalid code.
      });
    }
  4. Behandeln Sie die Überprüfung der E-Mail-Adresse, indem Sie applyActionCode aufrufen. Zum Beispiel:

    Web modular API

    function handleVerifyEmail(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      // Try to apply the email verification code.
      applyActionCode(auth, actionCode).then((resp) => {
        // Email address has been verified.
    
        // TODO: Display a confirmation message to the user.
        // You could also provide the user with a link back to the app.
    
        // TODO: If a continue URL is available, display a button which on
        // click redirects the user back to the app via continueUrl with
        // additional state determined from that URL's parameters.
      }).catch((error) => {
        // Code is invalid or expired. Ask the user to verify their email address
        // again.
      });
    }

    Web namespaced API

    function handleVerifyEmail(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      // Try to apply the email verification code.
      auth.applyActionCode(actionCode).then((resp) => {
        // Email address has been verified.
    
        // TODO: Display a confirmation message to the user.
        // You could also provide the user with a link back to the app.
    
        // TODO: If a continue URL is available, display a button which on
        // click redirects the user back to the app via continueUrl with
        // additional state determined from that URL's parameters.
      }).catch((error) => {
        // Code is invalid or expired. Ask the user to verify their email address
        // again.
      });
    }
  5. Hosten Sie die Seite irgendwo, beispielsweise mit Firebase Hosting .

Als Nächstes müssen Sie Ihr Firebase-Projekt so konfigurieren, dass es in seinen Benutzerverwaltungs-E-Mails eine Verknüpfung zu Ihrem benutzerdefinierten E-Mail-Aktionshandler herstellt.

So konfigurieren Sie Ihr Firebase-Projekt für die Verwendung Ihres benutzerdefinierten E-Mail-Aktionshandlers:

  1. Öffnen Sie Ihr Projekt in der Firebase-Konsole .
  2. Gehen Sie zur Seite „E-Mail-Vorlagen“ im Abschnitt „Authentifizierung “.
  3. Klicken Sie in einem der E-Mail-Typen- Einträge auf das Stiftsymbol, um die E-Mail-Vorlage zu bearbeiten.
  4. Klicken Sie auf Aktions-URL anpassen und geben Sie die URL für Ihren benutzerdefinierten E-Mail-Aktionshandler an.

Nachdem Sie die URL gespeichert haben, wird sie von allen E-Mail-Vorlagen Ihres Firebase-Projekts verwendet.