Créer des gestionnaires d'actions de messagerie personnalisés

Certaines actions de gestion des utilisateurs, comme la mise à jour de l'adresse e-mail d'un utilisateur et la réinitialisation de son mot de passe, entraînent l'envoi d'e-mails à l'utilisateur. Ces e-mails contiennent des liens que les destinataires peuvent ouvrir pour effectuer ou annuler l'action de gestion des utilisateurs. Par défaut, les e-mails de gestion des utilisateurs renvoient au gestionnaire d'actions par défaut, qui est une page Web hébergée à une URL dans le domaine Firebase Hosting de votre projet.

Vous pouvez plutôt créer et héberger un gestionnaire d'actions d'e-mail personnalisé pour effectuer un traitement personnalisé et intégrer le gestionnaire d'actions d'e-mail à votre site Web.

Les actions de gestion des utilisateurs suivantes nécessitent que l'utilisateur les effectue à l'aide d'un gestionnaire d'actions par e-mail :

  • Réinitialiser les mots de passe
  • Révocation des modifications d'adresse e-mail : lorsque les utilisateurs modifient l'adresse e-mail principale de leur compte, Firebase envoie un e-mail à leur ancienne adresse pour leur permettre d'annuler la modification.
  • Valider des adresses e-mail

Pour personnaliser le gestionnaire d'actions par e-mail de votre projet Firebase, vous devez créer et héberger une page Web qui utilise le SDK JavaScript Firebase pour vérifier la validité de la requête et la traiter. Vous devez ensuite personnaliser les modèles d'e-mails de votre projet Firebase pour les associer à votre gestionnaire d'actions personnalisé.

Créer la page du gestionnaire d'actions par e-mail

  1. Firebase ajoute plusieurs paramètres de requête à l'URL du gestionnaire d'actions lorsqu'il génère des e-mails de gestion des utilisateurs. Exemple : 

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

    Ces paramètres spécifient la tâche de gestion des utilisateurs que l'utilisateur effectue. La page de votre gestionnaire d'actions d'e-mails doit gérer les paramètres de requête suivants :

    Paramètres
    Standard

    Action de gestion des utilisateurs à effectuer. Les valeurs possibles sont les suivantes :

    • resetPassword
    • recoverEmail
    • verifyEmail
    oobCode Code à usage unique permettant d'identifier et de valider une demande
    apiKey Clé API de votre projet Firebase, fournie pour plus de commodité
    continueUrl Il s'agit d'une URL facultative qui permet de renvoyer l'état à l'application via une URL. Cela concerne les modes de réinitialisation du mot de passe et de validation de l'adresse e-mail. Lors de l'envoi d'un e-mail de réinitialisation ou de validation du mot de passe, un objet ActionCodeSettings doit être spécifié avec une URL de poursuite pour que cette option soit disponible. Cela permet à un utilisateur de reprendre exactement là où il s'était arrêté après une action par e-mail.
    lang

    Il s'agit de la balise de langue BCP47 facultative qui représente les paramètres régionaux de l'utilisateur (par exemple, fr). Vous pouvez utiliser cette valeur pour fournir à vos utilisateurs des pages de gestionnaires d'actions d'e-mails localisées.

    La localisation peut être définie dans la console Firebase ou de manière dynamique en appelant l'API client correspondante avant de déclencher l'action d'envoi d'e-mail. Par exemple, en utilisant JavaScript : firebase.auth().languageCode = 'fr';.

    Pour une expérience utilisateur cohérente, assurez-vous que la localisation du gestionnaire d'actions d'e-mail correspond à celle du modèle d'e-mail.

    L'exemple suivant montre comment gérer les paramètres de requête dans un gestionnaire basé sur un navigateur. (Vous pouvez également implémenter le gestionnaire en tant qu'application Node.js à l'aide d'une logique similaire.)

    Web

    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

    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. Gérez les demandes de réinitialisation de mot de passe en vérifiant d'abord le code d'action avec verifyPasswordResetCode, puis obtenez un nouveau mot de passe de l'utilisateur et transmettez-le à confirmPasswordReset. Exemple :

    Web

    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

    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. Gérez les révocations de modification d'adresse e-mail en vérifiant d'abord le code d'action avec checkActionCode, puis restaurez l'adresse e-mail de l'utilisateur avec applyActionCode. Exemple :

    Web

    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

    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. Gérez la validation de l'adresse e-mail en appelant applyActionCode. Exemple :

    Web

    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

    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. Hébergez la page quelque part, par exemple en utilisant Firebase Hosting.

Le backend Firebase Authentication gère la clé API intégrée aux liens d'action générés, tels que le paramètre apiKey dans l'URL. Si vous renouvelez les clés API de votre projet ou supprimez la clé initialement associée à Firebase Auth, vos utilisateurs peuvent recevoir des liens avec des clés non valides, ce qui entraîne des erreurs auth/invalid-api-key.

Pour remédier à ce problème, procédez comme suit :

  • Si vous utilisez Firebase Hosting : la clé API peut être mise en cache dans init.json. Déployez une nouvelle version de votre site d'hébergement (firebase deploy --only hosting) pour forcer le service de métadonnées de backend à régénérer la configuration avec la clé API active.
  • Si la clé de backend elle-même doit être mise à jour : comme le mappage de la clé d'API de backend ne peut pas être modifié directement à l'aide de la console ni des SDK, vous devez contacter l'assistance pour demander une mise à jour de la configuration d'authentification du backend pour votre projet.

Vous devez ensuite configurer votre projet Firebase pour l'associer à votre gestionnaire d'actions d'e-mail personnalisé dans ses e-mails de gestion des utilisateurs.

Pour configurer votre projet Firebase afin qu'il utilise votre gestionnaire d'actions de messagerie personnalisé :

  1. Dans la console Firebase, accédez à l'onglet Sécurité > Authentification > Modèles.

  2. Dans l'une des entrées Types d'e-mails, cliquez sur l'icône en forme de crayon pour modifier le modèle d'e-mail.

  3. Cliquez sur Personnaliser l'URL d'action, puis spécifiez l'URL de votre gestionnaire d'actions d'e-mail personnalisé.

Une fois l'URL enregistrée, elle sera utilisée par tous les modèles d'e-mails de votre projet Firebase.