Personnaliser la sélection MFA dans Universal Login

Personnalisez les flux MFA à l’aide d’Actions post-login pour demander aux utilisateurs de s’authentifier avec des facteurs précis ou une séquence de facteurs.

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

• Cette fonctionnalité vous permet de personnaliser vos flux de sélection MFA. Si vous souhaitez personnaliser vos flux d’inscription à la MFA, consultez Personnaliser les inscriptions MFA dans Universal Login.
• Vous ne pouvez personnaliser les flux MFA avec Actions que si vous utilisez Universal Login.
• Certaines méthodes décrites ne peuvent être utilisées que dans Universal Login, et non dans Connexion classique. Pour en savoir plus, consultez Personnaliser la MFA pour Connexion classique.

​

Fonctionnement

Vous pouvez utiliser les Actions pour personnaliser vos flux MFA. Plus précisément, vous pouvez modifier le déclencheur post-login du flux de connexion au moyen des méthodes suivantes de l’API d’authentification :

• challengeWith : spécifie 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 un défi par défaut aux utilisateurs et peut aussi, au besoin, donner accès à un sélecteur de facteurs qui leur permet de choisir une autre méthode d’authentification.

• challengeWithAny : définit un ensemble de facteurs parmi lesquels les utilisateurs peuvent choisir au moment de 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’un défi précis, 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’est inscrit 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’est inscrit à aucun des facteurs précisés, la commande échoue.

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

Lorsque vous choisissez des défis MFA pour vos commandes, vous pouvez utiliser les facteurs indiqué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 à 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’un défi MFA est exécuté, methods contient un objet name:mfa dont type est défini sur le facteur utilisé pour ce défi. methods n’est mis à jour qu’au début d’une Action. Pour voir les résultats d’un défi, il faut accéder à methods dans l’Action suivante du flux.

Pour en savoir plus, consultez les ressources suivantes :

• Déclencheurs Actions : post-login - objet Event
• Déclencheurs Actions : post-login - objet API

​

Flux séquencés et contextuels

Avec les commandes challengeWith ou challengeWithAny, vous pouvez utiliser des informations contextuelles 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 les éléments suivants :

• Flux séquencés : présentez aux utilisateurs une série de facteurs différents dans un ordre précis.
• Flux contextuels : déterminez quel facteur utiliser pour la prochaine demande de vérification de l’utilisateur en fonction des demandes de vérification précédentes dans le flux.

Pour illustrer ces flux, prenez 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 est d’abord invité à effectuer une vérification par SMS au moyen de la commande challengeWithAny dans Action 1. Ensuite, Action 2 invite l’utilisateur à confirmer son identité au moyen d’une notification push, puisqu’il a le rôle d’utilisateur Admin et qu’il a aussi réussi la vérification par SMS.

Dans ce flux, vous pouvez décider quel facteur demander à l’utilisateur pour les raisons suivantes :

1. Le flux est mis en pause après l’exécution d’Action 1.
2. L’utilisateur termine le flux MFA déclenché par Action 1.
3. event.authentication.methods.type dans Action 2 est renseigné avec l’information provenant de la vérification MFA précédente.
4. Le flux reprend ensuite pour exécuter 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 distincts suivants :

• Les flux sont mis en pause après chaque commande, ce qui vous permet d’accumuler des renseignements sur l’utilisateur pouvant être utilisés dans des Actions subséquentes. À l’inverse, les redirections ne se produisent qu’une seule fois, comme commande finale d’un flux.
• La MFA est déclenchée après l’exécution de chaque Action contenant des commandes challengeWith ou challengeWithAny. Avec les redirections, la MFA s’exécute dans la dernière Action du pipeline.

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

​

Avant de commencer

Avant de pouvoir personnaliser vos flux MFA, vous devez d’abord activer la MFA dans votre locataire et inviter vos utilisateurs à s’inscrire aux facteurs appropriés.

​

Préparez votre locataire

Pour commencer, configurez la MFA dans votre locataire et activez le paramètre Customize MFA Factors using Actions. Vous pouvez configurer un ou plusieurs facteurs et définir vos politiques de MFA dans le Auth0 Dashboard, sous Security > Multifactor 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 flux, vous devez activer l’option Customize MFA Factors using Actions dans la section Additional Settings. Vos flux 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 activées au moyen de api.multifactor.enable. Elles ont également préséance sur les paramètres de MFA offerts sous Define Policies.
• Pour vous assurer que les utilisateurs effectuent la MFA 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 solution de rechange et empêche les utilisateurs de contourner la MFA.
• Si vous souhaitez utiliser des évaluateurs de risque dans vos commandes, activez l’option Adaptive MFA Risk Assessment et utilisez event.authentication.riskAssessment dans votre code Actions post-login.

​

Inscrire des 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 authentificateurs avant de pouvoir faire l’objet d’une demande de vérification par des commandes Action post-login.

Après l’inscription d’un utilisateur ou sa création dans votre locataire, vous pouvez créer des inscriptions à l’aide du point de terminaison Management API authentication-methods, ou gérer directement les inscriptions des utilisateurs depuis leurs pages de profil dans Auth0 Dashboard.

​

Personnalisez vos flux MFA

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

Les Actions (ou séries d’Actions) d’un locataire 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 est exécutée), 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. Sous Add Action, sélectionnez Custom, puis choisissez Create Action.

3. Dans la fenêtre Create Action :

   • Saisissez un nom pour votre Action.
   • Sélectionnez Login / Post-Login comme déclencheur.
   • Utilisez Node 22 (Recommended) comme environnement d’exécution.

4. Vérifiez les renseignements dans la fenêtre contextuelle pour vous assurer qu’ils sont exacts. Ensuite, sélectionnez Create.

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

6. Lorsque votre fonction est prête, 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 fonction depuis le panneau Add Action dans votre flux Login. Ensuite, sélectionnez Apply.

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

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

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

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

​

Testez votre Action post-login

Pour vous assurer que votre code fonctionne correctement, vous pouvez tester votre Action dans Auth0 Dashboard :

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

Si tout se déroule correctement, 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 Auth0 Dashboard.

​

Exemples de cas d’utilisation

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

​

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

L’exemple suivant demande une vérification MFA à un utilisateur s’il 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 exige une vérification OTP pour tous les utilisateurs. Si un utilisateur a le rôle Admin et qu’il a besoin d’un niveau d’accès plus élevé à votre application, un facteur supplémentaire lui est demandé dans le cadre d’une 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’Organisation. Cet exemple utilise différentes catégories de métadonnées pour déterminer la vérification appropriée pour chaque utilisateur :

• Métadonnées de l’organisation : données propres à l’organisation, comme les facteurs précis activés pour une organisation.
• Métadonnées de l’utilisateur : données propres à 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 des facteurs activés pour l'organisation
  const availableFactors = orgFactors.filter(f => event.user?.enrolledFactors?.some(ef => ef.type === f));

  // Préférer 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 rechange
  // 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 rechange s'il est 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 sélectionner une méthode d’authentification différente de celle proposé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 le facteur de leur choix.

Facteur précis

L’exemple suivant demande un OTP par défaut aux utilisateurs. 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 inscrits

Dans l’exemple suivant, les utilisateurs doivent par défaut s’authentifier au moyen d’un OTP. Au besoin, ils peuvent cliquer sur le lien Essayer une autre méthode pour s’authentifier avec l’un de leurs autres facteurs déjà inscrits.

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

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

​

Utiliser l’Adaptive MFA pour déterminer quand demander une vérification supplémentaire aux utilisateurs

L’exemple suivant utilise l’Adaptive MFA pour déterminer si une vérification supplémentaire doit être demandée aux utilisateurs.

Adaptive MFA est une stratégie MFA flexible qui protège votre locataire contre les acteurs malveillants en évaluant le risque potentiel lors des tentatives de connexion et en demandant une vérification supplémentaire aux utilisateurs lorsque cela est approprié.

Dans ce cas, les utilisateurs sont invités à effectuer la MFA s’ils se connectent depuis un appareil non reconnu et que leur score global de confiance 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 la MFA uniquement en fonction du niveau de confiance 
    // NewDevice ; cela déclenchera la MFA lorsqu'un utilisateur se connecte 
    // depuis 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 la MFA.
        shouldPromptMfa = false;
        break;
    }

      // Il est pertinent de demander la MFA uniquement lorsque l'utilisateur possède au moins 
      // un facteur MFA 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 de connexion. Cet exemple utilise la méthode d’authentification phone et preferredMethod: 'both' pour faire référence aux facteurs MFA actifs associés au compte d’un utilisateur. Pour en savoir plus, consultez Actions Triggers: post-login - Event Object.

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

​

Dépannage

Si vous obtenez des erreurs ou des résultats inattendus dans vos flux MFA personnalisés, consultez les renseignements ci-dessous pour vous aider à identifier 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 constatez un comportement inattendu, consultez les journaux du locataire pour obtenir plus d’information sur les codes d’événement suivants :

Scénario	Code d’événement	Erreur descriptive
On demande à un utilisateur d’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 entraîne 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.
On demande à un utilisateur d’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 à l’aide d’un autre facteur demandé.	w	Ce scénario entraîne 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 du dépannage

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

1. Le bouton bascule Customize MFA factors with Actions doit être activé.

   • Accédez à Auth0 Dashboard > Security > Multi-factor Auth et assurez-vous que le bouton bascule de la section Additional Settings est activé.

2. Les facteurs référencés dans vos Actions doivent être activés dans votre locataire.

   • Vérifiez votre code : accédez à Auth0 Dashboard > Actions > Library > Custom et examinez le code de vos Actions. Assurez-vous que tous les facteurs référencés correspondent à vos cas d’utilisation.
   • Vérifiez vos facteurs : accédez à Auth0 Dashboard > Security > Multi-factor Auth et assurez-vous que tous les facteurs référencés dans vos Actions sont activés.

3. Les utilisateurs doivent être inscrits aux facteurs référencés dans vos Actions.

   • Si une personne reçoit une erreur, vérifiez les détails de son profil 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.

     • Vérifiez la section Multi-factor Authentication dans l’onglet Detail pour confirmer 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. Cette information peut également être récupérée à l’aide de la Management API. Il est toutefois 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 par courriel.

   • Si les utilisateurs ne sont pas inscrits aux facteurs appropriés, vous pouvez créer des inscriptions avec le point de terminaison authentication-methods de la Management API. Vous pouvez également gérer directement les inscriptions des utilisateurs à partir de leurs pages de profil dans le 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 indiqué, ouvrez votre Action, vérifiez votre code 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 faites glisser votre Action dans votre flux Login. Ensuite, sélectionnez Apply.

5. Assurez-vous d’avoir effectué la mise à 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.