Personnaliser l’inscription à la MFA pour Universal Login

Personnalisez les flux MFA à l’aide d’Actions post-connexion pour inviter les utilisateurs à s’inscrire à des facteurs spécifiques.

Auth0 prend en charge divers 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’inscrire à des facteurs spécifiques. Une fois inscrit à un facteur, l’utilisateur peut l’utiliser comme méthode d’authentification secondaire lors de connexions futures.

Vous pouvez aussi utiliser des informations contextuelles pour personnaliser davantage vos flux d’inscription à la MFA. Par exemple, vous pouvez inviter les utilisateurs à s’inscrire par SMS pour une application, et aux notifications push ou à WebAuthn pour une autre.

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

​

Fonctionnement

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

• enrollWith : Spécifie le facteur par défaut présenté aux utilisateurs pendant l’inscription. Vous pouvez aussi fournir une liste de facteurs parmi lesquels les utilisateurs pourront choisir. Le cas échéant, un lien Essayer une autre méthode s’affiche dans l’invite d’inscription.

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

  • Si au moins deux facteurs ont été spécifiés, l’invite de sélection s’affiche à l’utilisateur.
  • Si l’utilisateur est déjà inscrit à tous les facteurs spécifiés sauf un, l’invite de sélection est ignorée et l’utilisateur est invité à s’inscrire au facteur restant.
  • Si l’utilisateur est déjà inscrit à tous les facteurs spécifié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’inscription à la MFA. Vous pouvez également 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’inscription 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 inscrit à un facteur, la valeur correspondante est ajoutée à enrolledFactors. Cette propriété représente la liste des facteurs actifs associés à son compte utilisateur.

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

Lorsqu’une inscription à la MFA se produit, 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 moment où une Action démarre pour la première fois. Vous pouvez accéder aux résultats d’un événement d’inscription dans l’Action suivante du flux.

Pour en savoir plus, consultez les ressources suivantes :

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

​

Flux séquencés et contextuels

Avec les commandes enrollWith ou enrollWithAny, vous pouvez utiliser des informations contextuelles pour déterminer l’inscription la plus appropriée, ou la série d’inscriptions la plus appropriée, à présenter aux utilisateurs.

• La commande enrollWith prend en charge un facteur initial ou par défaut, ainsi qu’une liste d’options. Les utilisateurs ne peuvent s’inscrire qu’à un seul facteur par commande.
• La commande enrollWithAny prend en charge une liste de facteurs. L’ordre dans lequel les facteurs sont spécifiés détermine la façon dont la liste s’affiche aux utilisateurs. Les utilisateurs ne peuvent s’inscrire qu’à un seul facteur par commande.

Avec ces commandes, vous pouvez notamment tirer parti de ce qui suit :

• Flux séquencés : Inscrire les utilisateurs à une série de facteurs dans un ordre précis.
• Flux contextuels : Déterminer quel facteur présenter à l’utilisateur en fonction des métadonnées ou des commandes précédentes dans le flux.

Pour illustrer ces flux, prenez l’exemple suivant :

// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // déjà inscrit, 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 soumettant un défi avec 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 s’inscrire à l’aide soit d’un mot de passe à usage unique (OTP), soit d’une clé de sécurité. À l’inverse, les utilisateurs ayant le rôle d’administrateur doivent s’inscrire aux deux facteurs.

L’Action 1 examine app_metadata pour déterminer si l’utilisateur est un administrateur, puis l’invite à s’inscrire à des facteurs précis. Si un utilisateur administrateur n’est inscrit qu’à l’OTP, il doit d’abord réussir un défi OTP pour terminer son authentification. Il est ensuite invité à s’inscrire avec des clés de sécurité (webauthn-roaming).

Pour assurer la sécurité des comptes d’utilisateur, les utilisateurs doivent réussir un défi MFA à l’aide de l’un de leurs enrolledFactors existants avant de pouvoir s’inscrire à des facteurs supplémentaires. Cette condition garantit que vous pouvez mettre en œuvre en toute sécurité une stratégie personnalisée d’inscription à la MFA après qu’une application utilisant déjà différents facteurs et configurations a été mise en service.

Le flux s’interrompt 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 les utilisateurs peuvent choisir entre réussir un défi ou s’inscrire à différents facteurs.

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

​

Avant de commencer

Avant de pouvoir personnaliser vos flux MFA, vous devez configurer MFA dans votre locataire 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 Security > Multi-factor Auth.

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

Pour personnaliser vos flux, vous devez activer le bouton 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 qui utilisent les commandes enrollWith ou enrollWithAny remplacent toute politique ou tout Rules existant qui active ou désactive MFA dans un locataire.

​

Personnaliser les flux d’inscription à la MFA

Après avoir configuré la MFA pour votre locataire, vous pouvez créer des Actions post-login afin de personnaliser vos flux d’inscription à la MFA.

Les Actions (ou séries d’Actions) d’un locataire ne peuvent exécuter que quatre des commandes suivantes au cours d’un même 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 du signe plus (+), puis choisissez Build from scratch.

3. Dans la fenêtre contextuelle 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 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 Action 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 Action du panneau Add Action dans votre flux Login. 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 et redéployer votre code au besoin.

​

Testez votre Action post-login

Pour vous assurer que vos commandes fonctionnent comme prévu, vous pouvez tester votre Action à partir de l’Auth0 Dashboard :

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

Si le flux 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 votre Auth0 Dashboard.

​

Exemple de cas d’utilisation

L’exemple ci-dessous présente un cas d’utilisation courant de personnalisation des flux d’inscription à la MFA.

​

Proposer aux utilisateurs des options d’inscription à la MFA

L’exemple suivant demande par défaut aux utilisateurs de s’authentifier au moyen d’un OTP. Au besoin, ils peuvent sélectionner le lien « Essayer une autre méthode » pour s’authentifier par courriel à la place.

​

Dépannage

Si vous rencontrez des erreurs ou obtenez des résultats inattendus avec vos processus d’inscription à la MFA personnalisés, vous pouvez utiliser les renseignements ci-dessous pour vous aider à identifier et à résoudre ces problèmes.

​

Journaux du locataire

Vous pouvez suivre vos inscriptions à la MFA personnalisées 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 les codes d’événement suivants afin d’en savoir plus :

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

​

Liste de vérification du 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. 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 dans 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. 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, vérifiez votre code, puis cliquez sur Deploy dans le coin supérieur droit.
   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 flux Login. Sélectionnez ensuite Apply.

4. Assurez-vous d’avoir mis à niveau vos Actions post-login vers leur 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 plus récente version des Actions post-login à déployer lorsque vous utilisez le Deploy CLI. Pour en savoir plus, consultez Configure the Deploy CLI.