Personnaliser la sélection MFA pour Universal Login

Personnalisez les flux MFA à l’aide d’Actions post-login pour soumettre les utilisateurs à des facteurs précis ou à des séquences de facteurs.

Auth0 prend en charge une variété de facteurs pour sécuriser l’accès des utilisateurs avec l’authentification multifacteur (MFA). À l’aide des Actions post-login, vous pouvez personnaliser vos flux MFA pour soumettre les utilisateurs à un facteur précis ou à une séquence de facteurs. Vous pouvez également utiliser des renseignements contextuels sur les utilisateurs et leurs Organizations pour créer des expériences plus personnalisées. Par exemple, vous pouvez personnaliser vos flux pour soumettre les utilisateurs à des facteurs précis selon leur appartenance à certaines Organizations ou selon les rôles qui leur sont attribués.

• Cette fonctionnalité vous permet de personnaliser vos flux de sélection MFA. Si vous souhaitez personnaliser vos flux d’enrôlement MFA, consultez Personnaliser les enrôlements MFA dans Universal Login.
• Vous pouvez personnaliser les flux MFA avec Actions uniquement si vous utilisez Universal Login.
• Certaines méthodes décrites ne peuvent être utilisées qu’avec Universal Login, et non avec Classic Login. Pour en savoir plus, consultez Personnaliser MFA pour Classic Login.

​

Fonctionnement

Vous pouvez utiliser Actions pour personnaliser vos flux MFA. Plus précisément, vous pouvez modifier le trigger post-login du Flux de connexion à l’aide des méthodes suivantes de l’Authentication API :

• challengeWith : précise le ou les facteurs que les utilisateurs doivent utiliser pour s’authentifier, comme un mot de passe à usage unique (OTP). Cette méthode présente une vérification par défaut aux utilisateurs et peut aussi, au besoin, leur donner accès à un sélecteur de facteurs qui leur permet de choisir une autre méthode d’authentification.

• challengeWithAny : définit un groupe de facteurs parmi lesquels les utilisateurs peuvent choisir pour s’authentifier, comme le courriel et l’OTP. Par défaut, cette méthode présente un sélecteur de facteurs aux utilisateurs plutôt qu’une vérification précise, selon les conditions suivantes :

  • Si au moins deux facteurs sont précisés, un sélecteur de facteurs s’affiche pour l’utilisateur.
  • Si l’utilisateur n’a configuré qu’un seul des facteurs précisés (ou si un seul facteur est fourni), le sélecteur de facteurs est ignoré.
  • Si l’utilisateur n’a configuré aucun des facteurs précisés, la commande échoue.

Vous pouvez combiner ces méthodes pour adapter vos flux MFA à vos besoins. Vous pouvez aussi intégrer des métadonnées utilisateur, comme les rôles ou les facteurs déjà utilisés, à ces méthodes afin de créer des flux plus personnalisés.

Lorsque vous choisissez des vérifications MFA pour vos commandes, vous pouvez utiliser les facteurs énumérés ci-dessous ou la valeur enrolledFactors. enrolledFactors représente la liste des facteurs actifs associés au compte d’un utilisateur.

• otp

• email

• push-notification

  • otpFallback

• phone

  • preferredMethod: voice
  • preferredMethod: sms
  • preferredMethod: both

• webauthn-platform

• webauthn-roaming

Le tableau event.authentication.methods comprend un champ type lorsque le nom de la méthode est défini sur mfa. type est une chaîne qui contient des valeurs de facteur correspondant à celles utilisées par le champ type de enrolledFactors (énumérées ci-dessus). Lorsqu’une vérification MFA est effectuée, methods contient un objet name:mfa dont type correspond au facteur utilisé pour cette vérification. methods n’est mis à jour qu’au démarrage d’une Action. Pour voir les résultats d’une vérification, vous devez accéder à methods dans l’Action suivante du flux.

Pour en savoir plus, consultez les ressources suivantes :

• Actions Triggers : post-login - objet Event
• Actions Triggers : post-login - objet API

​

Parcours séquencés et contextuels

Avec les commandes challengeWith ou challengeWithAny, vous pouvez utiliser des renseignements contextuels pour déterminer la meilleure demande de vérification, ou la meilleure série de demandes de vérification, à présenter aux utilisateurs. Plus précisément, vous pouvez vous appuyer sur ce qui suit :

• Parcours séquencés : soumettez les utilisateurs à une série de facteurs différents dans un ordre précis.
• Parcours contextuels : déterminez quel facteur utiliser pour la prochaine demande de vérification en fonction des demandes de vérification précédentes dans le parcours.

Pour illustrer ces parcours, prenons l’exemple suivant :

// ACTION 1 

exports.onExecutePostLogin = async (event, api) => {

   api.authentication.challengeWithAny([{ type: 'phone'}, { type: 'push-notification' }]);

} 

// ============================================ 

// ACTION 2 

// Décider en fonction de ce que l'utilisateur a fait dans l'action précédente 

exports.onExecutePostLogin = async (event, api) => { 

    if(event.authentication.methods.find(m => m.type === 'phone') && event.authorization?.roles.includes('admin')) { 

        api.authentication.challengeWith({ type: 'push-notification' }); 

    }

}

Dans ce scénario, un utilisateur reçoit d’abord une demande de vérification par SMS au moyen de la commande challengeWithAny dans Action 1. Ensuite, Action 2 soumet l’utilisateur à une vérification par notification push, parce qu’il a le rôle d’utilisateur Admin et qu’il a aussi complété la vérification par SMS.

Dans ce flow, vous pouvez déterminer quel factor utiliser pour soumettre l’utilisateur à une vérification pour les raisons suivantes :

1. Le flow se met en pause après l’exécution d’Action 1.
2. L’utilisateur complète le flow MFA déclenché par Action 1.
3. event.authentication.methods.type dans Action 2 se remplit avec l’information provenant du challenge MFA précédent.
4. Le flow reprend et exécute Action 2 en utilisant l’information contextuelle d’Action 1.

Bien que cet exemple offre une expérience semblable à l’utilisation de redirections dans vos Actions, les commandes challengeWith et challengeWithAny offrent les avantages uniques suivants :

• Les flows se mettent en pause après chaque commande, ce qui vous permet d’accumuler de l’information sur l’utilisateur qui pourra être utilisée dans les Actions suivantes. À l’inverse, les redirections ne se produisent qu’une seule fois, comme commande finale dans un flow.
• La MFA est déclenchée après l’exécution de chaque Action contenant les commandes challengeWith ou challengeWithAny. Avec les redirections, la MFA s’exécute dans l’Action finale du pipeline.

Remarque : Cette méthode d’exécution des Actions s’applique uniquement à celles qui contiennent les commandes challengeWith ou challengeWithAny. Les Actions qui servent à d’autres fins ne sont pas touchées.

​

Avant de commencer

Avant de pouvoir personnaliser vos flux MFA, vous devez d’abord activer MFA dans votre tenant et inviter vos utilisateurs à configurer les facteurs appropriés.

​

Préparez votre tenant

Pour commencer, configurez l’authentification multifacteur dans votre tenant et activez le paramètre Customize MFA Factors using Actions. Vous pouvez configurer un ou plusieurs facteurs et définir vos politiques MFA dans le Auth0 Dashboard, sous Sécurité > Multi-factor Auth.

• Pour en savoir plus sur le processus de configuration, consultez Activer l’authentification multifacteur.
• Pour obtenir plus d’information sur la configuration de facteurs précis, consultez Facteurs d’authentification multifacteur.

Pour personnaliser vos flows, vous devez activer la bascule Customize MFA Factors using Actions dans la section Additional Settings. Vos flows personnalisés ne fonctionneront pas correctement si ce paramètre n’est pas activé.

• Les Actions qui invoquent les commandes challengeWith et challengeWithAny remplacent toutes les vérifications supplémentaires activées au moyen de api.multifactor.enable. Elles ont aussi préséance sur les paramètres MFA offerts sous Define Policies.
• Pour vous assurer que les utilisateurs effectuent l’authentification multifacteur lorsqu’ils tentent d’accéder à votre application, réglez le paramètre Require Multi-factor Auth sur Use Adaptive MFA ou Always. Si votre code Actions ne s’exécute pas, ce paramètre sert de mesure de secours et empêche les utilisateurs de contourner la MFA.
• Si vous souhaitez utiliser des évaluateurs de risque dans vos commandes, activez la bascule Adaptive MFA Risk Assessment et utilisez event.authentication.riskAssessment dans votre code Actions post-login.

​

Inscrire les utilisateurs à des facteurs

Une fois la MFA configurée, assurez-vous que vos utilisateurs s’inscrivent à un ou plusieurs des facteurs que vous avez activés. Les utilisateurs doivent s’inscrire à des authenticators avant de pouvoir faire l’objet d’une demande de vérification par les commandes d’Action post-login.

Après l’inscription d’un utilisateur ou sa création dans votre tenant, vous pouvez créer des inscriptions à l’aide de l’Management API endpoint authentication-methods, ou vous pouvez gérer directement les inscriptions des utilisateurs à partir de leur page de profil dans l’Auth0 Dashboard.

​

Personnalisez vos flux MFA

Une fois que votre tenant est prêt, vous pouvez créer des Actions post-login pour personnaliser vos flux MFA. Les étapes et des exemples de cas d’utilisation sont fournis ci-dessous.

Les Actions (ou séries d’Actions) d’un tenant ne peuvent exécuter que quatre des commandes suivantes par flux utilisateur :

• enrollWith
• enrollWithAny
• challengeWith
• challengeWithAny

Si cette limite est dépassée (c.-à-d. si une cinquième commande de ce type tente de s’exécuter), une erreur d’authentification se produira.

​

Créez votre Action post-login

1. Dans votre Auth0 Dashboard, accédez à Actions > Flows et sélectionnez Login.

2. Dans la section Add Action, sélectionnez Custom, puis choisissez Create Action.

3. Dans la fenêtre contextuelle Create Action :

   • Entrez un nom pour votre Action.
   • Sélectionnez Login / Post-Login comme trigger.
   • Utilisez Node 22 (Recommended) pour le runtime.

4. Vérifiez la fenêtre contextuelle pour vous assurer que tout est exact. Ensuite, sélectionnez Create.

5. Après la création, l’éditeur de code affiche la fonction onPostExecute. Ajoutez-y votre code personnalisé ou l’exemple de code.

6. Lorsque votre code est prêt, sélectionnez Deploy.

7. Sélectionnez Add to Flow dans la notification de déploiement réussi.

   • Remarque : Si la notification s’est fermée, choisissez Back to Flow au-dessus de l’éditeur de code.

8. Glissez-déposez votre nouvelle Action depuis le panneau Add Action vers votre Login flow. Ensuite, sélectionnez Apply.

Pour apporter d’autres modifications à votre Action, accédez à Actions > Library > Custom et sélectionnez votre Action. Vous pourrez ensuite mettre à jour et redéployer votre code au besoin.

Lorsque vous ajoutez une redirection à votre MFA flow, assurez-vous que votre Action respecte les conditions suivantes afin d’empêcher les utilisateurs d’ignorer ou de contourner la MFA :

• La commande de redirection (sendUserTo) doit se trouver dans une Action distincte de vos commandes MFA.
• L’Action de redirection doit être la dernière Action exécutée dans votre flow.

Pour en savoir plus sur les redirections, consultez Redirect with Actions.

​

Testez votre Action post-login

Pour vérifier que vos commandes fonctionnent comme prévu, vous pouvez tester votre Action dans l’Auth0 Dashboard :

• Accédez à Authentication > Authentication Profile.
• Sélectionnez Try pour ouvrir un exemple d’écran de connexion dans un nouvel onglet.
• Entrez vos identifiants et testez votre nouveau flux MFA.

Si le flux est réussi, un écran de confirmation s’affiche. Si vous rencontrez des problèmes, vous pouvez mettre à jour votre code en accédant à Actions > Library > Custom dans votre Auth0 Dashboard.

​

Exemples de cas d’utilisation

Les exemples ci-dessous illustrent des cas d’utilisation courants pour personnaliser les flux d’AMF.

​

Utiliser les inscriptions actuelles pour déterminer la méthode de vérification

L’exemple suivant lance une vérification MFA pour un utilisateur si celui-ci est inscrit aux facteurs suivants :

• Mot de passe à usage unique (OTP)
• Téléphone

exports.onExecutePostLogin = async (event, api) => {

 api.authentication.challengeWithAny([{type: 'otp'}, {type: 'phone'}]);

}

​

Utiliser les rôles pour déterminer la méthode de vérification

L’exemple suivant soumet tous les utilisateurs à une vérification par OTP. Si un utilisateur a le rôle Admin et a besoin d’un niveau d’accès plus élevé à votre application, il doit effectuer une vérification supplémentaire au moyen d’un facteur additionnel, sous forme d’authentification renforcée.

exports.onExecutePostLogin = async (event, api) => {
    api.authentication.challengeWith({type: 'otp'});

    const isAdmin = event.authorization?.roles.includes('admin');
    if(isAdmin) {
        api.authentication.challengeWith({type: 'phone'});
    }
}

​

Utiliser les métadonnées pour déterminer la méthode de vérification

Dans cet exemple, les facteurs MFA sont activés au niveau de l’Organization. Cet exemple s’appuie sur différentes catégories de métadonnées pour déterminer le mode de vérification approprié pour chaque utilisateur :

• Métadonnées de l’organisation : données au niveau de l’organisation, comme les facteurs précis activés pour une organisation donnée.
• Métadonnées de l’utilisateur : données au niveau de l’utilisateur, par exemple si un utilisateur a un numéro de téléphone associé à son profil.

exports.onExecutePostLogin = async (event, api) => {
  const orgFactors = event.organization?.metadata.factors.split(',') ?? [];

  // Obtenir l'intersection des facteurs disponibles pour l'utilisateur et ceux activés pour l'organisation
  const availableFactors = orgFactors.filter(f => event.user?.enrolledFactors?.some(ef => ef.type === f));

  // Privilégier push si disponible
  if(availableFactors.includes('push-notification')) {
    api.authentication.challengeWith({ type: 'push-notification' });
    return;
  }

  // Si l'utilisateur a un numéro de téléphone vérifié et que l'organisation
  // autorise les SMS et le courriel, privilégier les SMS et autoriser le courriel comme solution de secours
  // si disponible
  if(event.user.phone_number && 
     event.user.phone_verified && 
     availableFactors.includes('phone')) {
    if(availableFactors.includes('email')) {
      api.authentication.challengeWith({ type: 'phone' }, {
        additionalFactors: [{
          type: 'email'
        }]
      });
    } else {
      api.authentication.challengeWith({ type: 'phone' });
    }

    return;
  }

  // Si les notifications push et/ou le téléphone n'ont pas pu être privilégiés, utiliser le courriel comme solution de secours si
  // activé pour l'organisation, sinon échouer.
  if(availableFactors.includes('email')) {
    api.authentication.challengeWith({ type: "email" });
    return;
  }

  api.access.deny("No MFA factors available for this org + user");
};

​

Permettre aux utilisateurs de sélectionner une autre méthode d’authentification

Pour offrir une expérience plus souple, vous pouvez présenter aux utilisateurs un lien Essayer une autre méthode dans le cadre de leur vérification MFA. Ce lien permet aux utilisateurs de choisir une méthode d’authentification différente de celle utilisée par défaut.

Pour ce faire, incluez le paramètre additionalFactors dans votre code Actions. Vous pouvez définir ce paramètre sur un facteur précis pour tous les utilisateurs ou utiliser enrolledFactors pour leur permettre de choisir leur facteur préféré.

Facteur précis

L’exemple suivant demande par défaut aux utilisateurs de s’authentifier avec un OTP. Au besoin, ils peuvent utiliser le lien Essayer une autre méthode pour s’authentifier plutôt par courriel.

exports.onExecutePostLogin = async (event, api) => {
  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: [{type: 'email'}] })
};

Facteurs configurés

L’exemple suivant demande par défaut aux utilisateurs de vérifier leur identité au moyen d’un OTP. Au besoin, ils peuvent sélectionner le lien Essayer une autre méthode pour s’authentifier à l’aide d’un autre facteur déjà configuré.

exports.onExecutePostLogin = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));

  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: enrolledFactors })
};

​

Utiliser Adaptive MFA pour déterminer quand soumettre les utilisateurs à une vérification supplémentaire

L’exemple suivant utilise Adaptive MFA pour déterminer si les utilisateurs doivent être soumis à une vérification.

Adaptive MFA est une politique MFA flexible qui protège votre tenant contre les acteurs malveillants en évaluant le risque potentiel pendant les tentatives de connexion et en demandant aux utilisateurs une vérification supplémentaire au besoin.

Dans ce cas, les utilisateurs sont invités à effectuer la MFA s’ils se connectent à partir d’un appareil non reconnu et que leur score de confiance global est faible ou moyen.

/**
* Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.
*
* @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.
* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication?.riskAssessment?.assessments.NewDevice) {

  // Exemple de condition : demander l'AMF uniquement en fonction du niveau de confiance 
    // de NewDevice ; cela déclenchera l'AMF lorsqu'un utilisateur se connecte 
    // à partir d'un appareil inconnu.
    let shouldPromptMfa;

    switch (event.authentication.riskAssessment.assessments.NewDevice.confidence) {
      case 'low':
      case 'medium':
        shouldPromptMfa = true;
        break;
      case 'high':
        shouldPromptMfa = false;
        break;
      case 'neutral':
        // Lorsque cet évaluateur ne dispose d'aucune information utile sur le niveau de confiance, 
        // ne pas demander l'AMF.
        shouldPromptMfa = false;
        break;
    }

      // Il est pertinent de demander l'AMF uniquement lorsque l'utilisateur possède au moins 
      // un facteur AMF inscrit.
    const canPromptMfa = event.user.enrolledFactors?.length > 0;

    if (shouldPromptMfa && canPromptMfa) {
      const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));
      api.authentication.challengeWithAny(enrolledFactors);
    }

  }

};

​

Utiliser Actions pour demander une vérification aux utilisateurs

Vous pouvez utiliser Actions pour personnaliser les flux MFA en modifiant le déclencheur post-login du flux Login. Cet exemple utilise la méthode d’authentication phone et preferredMethod: 'both', qui fait référence aux facteurs MFA actifs associés au compte d’un utilisateur. Pour en savoir plus, consultez Déclencheurs Actions : post-login - objet Event.

api.authentication.challengeWith({ 
  type: 'phone', 
  options: { preferredMethod: 'both'} 
});

​

Dépannage

Si vous rencontrez des erreurs ou des résultats inattendus dans vos flux MFA personnalisés, les renseignements ci-dessous vous aideront à cerner et à résoudre ces problèmes.

​

Journaux du locataire

Vous pouvez surveiller vos flux MFA personnalisés au moyen des journaux du locataire.

Les journaux du locataire sont accessibles dans l’Auth0 Dashboard sous Monitoring > Logs. Vous pouvez aussi récupérer les journaux à l’aide de la Management API.

Si vous ou vos utilisateurs observez un comportement inattendu, consultez les journaux du locataire pour les codes d’événement suivants afin d’obtenir plus d’information :

Scénario	Event Code	Erreur descriptive
Un utilisateur doit effectuer une authentification multifacteur, mais aucun des facteurs demandés ne peut servir à la vérification. Dans ce cas, l’utilisateur ne peut pas terminer la MFA.	mfar	Ce scénario produit le message d’erreur suivant : Une vérification MFA est utilisée dans une action PostLogin, mais les facteurs demandés ne sont pas configurés correctement. Pour effectuer la MFA, activez les facteurs demandés et assurez-vous que l’utilisateur y est inscrit.
Un utilisateur doit effectuer une authentification multifacteur, mais l’un des facteurs demandés ne peut pas servir à la vérification. Dans ce cas, l’utilisateur peut terminer la MFA au moyen d’un autre facteur demandé.	w	Ce scénario produit le message d’avertissement suivant : Une vérification MFA est utilisée dans une action PostLogin, mais le facteur demandé {factor name} n’est pas configuré correctement. Activez le facteur demandé et assurez-vous que l’utilisateur y est inscrit.

​

Liste de vérification de dépannage

La liste de vérification suivante propose des suggestions supplémentaires pour repérer et résoudre les problèmes courants liés aux flux MFA personnalisés.

1. La bascule Customize MFA factors with Actions doit être activée.

   • Accédez à Auth0 Dashboard > Sécurité > Multi-factor Auth et assurez-vous que la bascule dans la section Additional Settings est activée.

2. Les facteurs mentionnés dans vos Actions doivent être activés dans votre tenant.

   • Passez votre code en revue : accédez à Auth0 Dashboard > Actions > Library > Custom et passez votre code Actions en revue. Assurez-vous que tous les facteurs mentionnés correspondent à vos cas d’utilisation.
   • Passez vos facteurs en revue : accédez à Auth0 Dashboard > Sécurité > Multi-factor Auth et assurez-vous que tous les facteurs mentionnés dans vos Actions sont activés.

3. Les utilisateurs doivent être inscrits aux facteurs mentionnés dans vos Actions.

   • Si une personne reçoit une erreur, consultez les détails de son compte utilisateur pour vous assurer qu’elle est inscrite aux bons facteurs. Accédez à Auth0 Dashboard > User Management > Users et sélectionnez son nom dans la liste.

     • Consultez la section Multi-factor Authentication dans l’onglet Detail pour vérifier ses inscriptions. Si l’utilisateur n’est pas inscrit, vous pouvez utiliser le lien Send an enrollment invitation offert dans cette section.
     • Vous pouvez aussi vérifier les inscriptions de l’utilisateur dans l’onglet Raw JSON. Vous pouvez également récupérer ces renseignements au moyen de la Management API. Cependant, il est important de noter que l’API ne répertorie pas les authentificateurs inscrits automatiquement, comme les facteurs Email configurés au moyen d’un lien de vérification.

   • Si les utilisateurs ne sont pas inscrits aux facteurs appropriés, vous pouvez créer des inscriptions à l’aide du endpoint authentication-methods de la Management API. Vous pouvez aussi gérer directement les inscriptions des utilisateurs à partir de leurs pages de profil dans l’Auth0 Dashboard.

4. Assurez-vous que vos Actions ont été déployées et enregistrées dans votre pipeline.

   • Accédez à Auth0 Dashboard > Actions > Library > Custom. Repérez votre Action dans la liste et assurez-vous que son statut est Deployed. Si un autre statut est affiché, ouvrez votre Action, passez votre code en revue et cliquez sur Deploy en haut à droite.
   • Accédez à Auth0 Dashboard > Actions > Library > Flows et sélectionnez Login. Assurez-vous que votre Action figure dans le flux. Sinon, ouvrez l’onglet Custom du panneau Add Action et glissez-déposez votre Action dans votre flux Login. Ensuite, sélectionnez Apply.

5. Assurez-vous d’avoir mis à niveau vers la version la plus récente des Actions post-login.

   • Accédez à Auth0 Dashboard > Actions > Library > Custom et sélectionnez votre Action. Si votre Action n’est pas à jour, une bannière jaune vous invitera à la mettre à jour. Si la bannière s’affiche, sélectionnez Update.
   • Vous pouvez aussi préciser la version la plus récente des Actions post-login à déployer lorsque vous utilisez le Deploy CLI. Pour en savoir plus, consultez Configure the Deploy CLI.