Personnaliser les enrôlements MFA pour Universal Login

Personnalisez les flux MFA à l’aide d’Actions post-login pour inviter les utilisateurs à s’enrôler à des facteurs précis.

Auth0 prend en charge différents 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 afin d’inviter les utilisateurs à s’enrôler à des facteurs précis. Une fois qu’un utilisateur s’est enrôlé à un facteur, il peut utiliser ce facteur comme méthode d’authentification secondaire lors de connexions ultérieures.

Vous pouvez aussi utiliser des informations contextuelles pour personnaliser davantage vos flux d’enrôlement MFA. Par exemple, vous pouvez inviter les utilisateurs à s’enrôler au facteur SMS pour une application, tout en les invitant à s’enrôler aux notifications push ou à WebAuthN pour une autre application.

Cette fonctionnalité vous permet de personnaliser vos flux d’enrôlement MFA. Si vous souhaitez personnaliser les flux MFA pour des utilisateurs déjà enrôlés, consultez Personnaliser la sélection MFA pour Universal Login.

​

Comment ça fonctionne

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

• enrollWith : indique le facteur par défaut présenté aux utilisateurs pendant l’enrôlement. Vous pouvez aussi, au besoin, fournir une autre liste de facteurs parmi lesquels les utilisateurs pourront choisir. Si cette liste est fournie, un lien Essayer une autre méthode s’affiche dans l’invite d’enrôlement.

• enrollWithAny : indique un ensemble de facteurs parmi lesquels les utilisateurs peuvent choisir pendant l’enrôlement. Par défaut, cette méthode affiche une invite de sélection permettant aux utilisateurs de choisir le facteur souhaité. Dans certains cas, l’expérience utilisateur peut varier :

  • Si au moins deux facteurs ont été précisés, l’invite de sélection s’affiche à l’utilisateur.
  • Si l’utilisateur est déjà enrôlé dans tous les facteurs précisés sauf un, l’invite de sélection est ignorée et l’utilisateur est invité à s’enrôler dans le facteur restant.
  • Si l’utilisateur est déjà enrôlé dans tous les facteurs précisés, la commande échoue et la séquence de connexion se poursuit.

Vous pouvez utiliser une combinaison de ces méthodes pour personnaliser vos flux d’enrôlement MFA. Vous pouvez aussi utiliser les métadonnées utilisateur, comme les rôles ou la date de dernière connexion, afin de créer des expériences plus adaptées.

Les flux d’enrôlement personnalisés prennent en charge les facteurs suivants :

• otp

• recovery-code

• push-notification

• phone

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

• webauthn-platform

• webauthn-roaming

Après qu’un utilisateur s’est enrôlé dans un facteur, sa valeur est ajoutée à enrolledFactors. Cette propriété représente la liste des facteurs actifs associés à son compte d’utilisateur.

Le tableau event.authentication.methods comprend un champ type lorsque le nom de la méthode est défini sur mfa. Ce champ contient des valeurs de facteur (string) qui correspondent à celles utilisées par le champ type de enrolledFactors.

Lorsqu’un enrôlement MFA a lieu, methods contient l’objet name:mfa avec type défini sur le facteur utilisé pour cet événement. methods et enrolledFactors ne sont mis à jour qu’au début d’une Action. Vous pouvez accéder aux résultats d’un événement d’enrôlement 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

​

Flux séquencés et contextuels

Avec les commandes enrollWith ou enrollWithAny, vous pouvez utiliser des informations contextuelles pour déterminer l’enrôlement, ou la série d’enrôlements, qu’il convient de présenter aux utilisateurs.

• La commande enrollWith prend en charge un facteur initial ou par défaut, ainsi qu’une liste de solutions de rechange. Les utilisateurs ne peuvent s’enrôler qu’à un seul facteur par commande.
• La commande enrollWithAny prend en charge une liste de facteurs. L’ordre indiqué détermine la façon dont la liste s’affiche aux utilisateurs. Les utilisateurs ne peuvent s’enrôler qu’à un seul facteur par commande.

Avec ces commandes, vous pouvez tirer parti des éléments suivants :

• Flux séquencés : enrôlez les utilisateurs à une série de facteurs dans un ordre précis.
• Flux contextuels : déterminez quel facteur proposer à l’utilisateur en fonction des métadonnées ou des commandes précédentes dans le flux.

Pour mieux illustrer ces flux, prenons l’exemple suivant :

// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // déjà inscrit, envoyer un défi
    api.authentication.challengeWithAny(event.user.enrolledFactors.map(m => ({type: m.type})));
    if (event.user.app_metadata.isAdmin &&
        !event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
          // si c'est un administrateur et qu'il n'a pas de clé de sécurité, ce qui signifie qu'un autre facteur a été utilisé, inscrire maintenant
          api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
  }
  else {
    // non inscrit ; choisir un facteur à inscrire maintenant
    api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    if (event.user.app_metadata.isAdmin) {
      // un facteur supplémentaire pour les administrateurs
      api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    }
  }
};

// Action 2

exports.onExecutePostLogin = async (event, api) => {
  function performed(type) {
    return event.authentication.methods.some(m => m.name === 'mfa' &&
           m.type === type &&
           Date.now() - new Date(m.timestamp).getTime() < 5000)
  }
  if (event.user.app_metadata.isAdmin) {
      // s'assurer que les deux facteurs sont utilisés en envoyant un défi pour celui qui n'a pas encore été utilisé
      if (!performed('webauthn-roaming')) {
        api.authentication.challengeWith({type: 'webauthn-roaming'})
      }
      else if (!performed('otp')) {
        api.authentication.challengeWith({type: 'otp'})
      }
  }
};

Ces deux Actions se combinent pour créer un scénario où les utilisateurs sans le rôle d’administrateur doivent enrôler soit un mot de passe à usage unique (OTP), soit une clé de sécurité. À l’inverse, les utilisateurs avec le rôle d’administrateur doivent enrôler les deux facteurs.

L’Action 1 vérifie le app_metadata pour déterminer si l’utilisateur est un administrateur, puis lui demande d’enrôler des facteurs précis. Si un utilisateur administrateur n’a enrôlé que l’OTP, il doit d’abord passer une vérification par OTP pour terminer son authentification. Il est ensuite invité à enrôler des clés de sécurité (webauthn-roaming).

Pour assurer la sécurité des comptes d’utilisateur, les utilisateurs doivent effectuer une vérification MFA à l’aide de l’un de leurs facteurs déjà enregistrés avant de pouvoir enrôler des facteurs supplémentaires. Cette condition garantit que vous pouvez mettre en œuvre en toute sécurité une politique personnalisée d’enrôlement MFA après qu’une application avec différents facteurs et configurations a déjà été utilisée.

Le flux est mis en pause après l’exécution de l’Action 1, et event.user.enrolledFactors ainsi que event.authentication.methods seront mis à jour lors de l’exécution de l’Action 2. Cela permet au code de l’Action de prendre des décisions en fonction des données réelles de l’utilisateur lorsque celui-ci a le choix d’effectuer une vérification ou d’enrôler différents facteurs.

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

​

Avant de commencer

Avant de pouvoir personnaliser vos flux MFA, vous devez configurer l’authentification multifacteur dans votre tenant et activer le paramètre Customize MFA Factors using Actions. Vous pouvez activer un ou plusieurs facteurs et définir vos politiques MFA dans votre 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 flux, vous devez activer la bascule 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é.

Remarque : Les Actions avec les commandes enrollWith ou enrollWithAny remplacent toute politique ou règle existante qui active ou désactive la MFA dans un tenant.

​

Personnaliser les flux d’enrôlement MFA

Après avoir configuré la MFA pour votre tenant, vous pouvez créer des Actions post-login pour personnaliser vos flux d’enrôlement MFA.

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

Vous pouvez créer des Actions dans l’Auth0 Dashboard :

1. Accédez à Actions > Flows et sélectionnez Login.

2. Dans le panneau Add Action, sélectionnez l’icône plus (+) et choisissez Build from scratch.

3. Dans la fenêtre contextuelle Create Action :

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

4. Vérifiez la fenêtre contextuelle pour vous assurer que tout est exact. Sélectionnez ensuite Create.

5. Dans l’éditeur de code, ajoutez votre code personnalisé à la commande onPostExecute.

6. Lorsque votre commande est prête, sélectionnez Deploy.

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

   • Remarque : Si la notification se ferme, choisissez Back to Flow au-dessus de l’éditeur de code.

8. Glissez-déposez votre nouvelle commande depuis le panneau Add Action dans votre Login flow. Sélectionnez ensuite Apply.

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

​

Testez votre Action post-login

Pour vous assurer que vos commandes fonctionnent correctement, vous pouvez tester votre Action dans l’Auth0 Dashboard :

1. Accédez à Authentication > Authentication Profile.
2. Sélectionnez Try pour ouvrir un exemple de login prompt dans un nouvel onglet.
3. Entrez vos informations d’identification 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.

​

Exemple de cas d’utilisation

L’exemple ci-dessous illustre un cas d’utilisation courant pour personnaliser les flux d’enrôlement MFA.

​

Proposer aux utilisateurs des options de MFA pour l’enrôlement

Dans l’exemple suivant, les utilisateurs doivent s’authentifier par OTP par défaut. S’ils le souhaitent, ils peuvent cliquer sur le lien Essayer une autre méthode pour s’authentifier plutôt par courriel.

​

Dépannage

Si vous rencontrez des erreurs ou des résultats inattendus avec vos enrôlements MFA personnalisés, consultez les renseignements ci-dessous pour vous aider à cerner et à résoudre ces problèmes.

​

Journaux du tenant

Vous pouvez surveiller vos enrôlements MFA personnalisés au moyen des journaux du tenant.

Les journaux du tenant 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 tenant pour les codes d’événement suivants afin d’en savoir plus :

Scénario	Événement	Message d’erreur
Un utilisateur est invité à s’enrôler à un facteur précis. Toutefois, le facteur demandé répond à l’une des conditions suivantes : Le facteur n’est pas activé dans votre tenant. Le facteur n’est pas pris en charge par le navigateur de l’utilisateur. L’utilisateur est déjà enrôlé au facteur demandé. Dans ce scénario, l’utilisateur peut terminer le flux si d’autres facteurs sont disponibles.	w	Un enrôlement MFA est utilisé 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 n’y est pas déjà enrôlé.
Un utilisateur est invité à s’enrôler à un ou plusieurs facteurs, mais les facteurs fournis ne peuvent pas être utilisés pour l’enrôlement. Dans ce cas, l’utilisateur ne peut pas terminer le flux.	mfar	Un enrôlement MFA est utilisé 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 n’y est pas déjà enrôlé.
Un utilisateur tente de s’enrôler à un nouveau facteur sans avoir effectué au moins une vérification au moyen d’un enrôlement existant.	mfar	Un enrôlement MFA a été demandé, mais l’utilisateur est déjà enrôlé à la MFA. Effectuez une vérification avec au moins un facteur existant avant d’en enrôler un nouveau.

​

Liste de vérification pour la résolution des problèmes

La liste de vérification suivante propose d’autres pistes 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 > Security > Multi-factor Auth et assurez-vous que la bascule de la section Additional Settings est activée.

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

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

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

   1. 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, puis cliquez sur Deploy en haut à droite.
   2. Accédez à Auth0 Dashboard > Actions > Library > Flows et sélectionnez Login. Assurez-vous que votre Action figure dans le flux. Sinon, accédez à l’onglet Custom du panneau Add Action et glissez-déposez votre Action dans votre Login flow. Ensuite, sélectionnez Apply.

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

   • 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.