Gestion de l’AMF utilisateur

Découvrez comment afficher une interface à cartes permettant aux utilisateurs d’inscrire, de consulter et de supprimer leurs propres facteurs d’authentification multifacteur à l’aide de l’API My Account.

Le composant UserMFAManagement permet aux utilisateurs d’inscrire, de consulter et de supprimer leurs propres facteurs d’authentification multifacteur dans une interface unique sous forme de cartes, grâce à l’API My Account.

Il utilise les capacités de gestion des méthodes d’authentification de l’API My Account pour afficher une interface complète de gestion des méthodes d’authentification d’un utilisateur.

Avec le composant UserMFAManagement, vous n’avez pas à gérer la navigation, à effectuer des requêtes vers des endpoints d’API ni à gérer l’état.

​

Facteurs pris en charge

Le composant prend en charge tous les facteurs de méthode d’authentification configurés avec la My Account API.

Facteur	Ce que le composant affiche
Email OTP	Saisie de l’adresse courriel → vérification par OTP à 6 chiffres
SMS OTP	Sélecteur d’indicatif de pays + saisie du numéro de téléphone → vérification par OTP à 6 chiffres
TOTP (application d’authentification)	Code QR avec clé de saisie manuelle → vérification par OTP à 6 chiffres
Notifications push	Code QR à balayer avec Auth0 Guardian → état « en attente d’approbation »
Clés d’accès	Écran d’information → invite biométrique du système d’exploitation → entrée enregistrée dans la liste
Codes de récupération	Liste de codes affichée une seule fois, avec une action de copie et une confirmation « J’ai enregistré mes codes »

​

Configurez votre application

Sélectionnez votre framework pour configurer les variables d’environnement et Universal Components.

React (SPA)

​

Exigences de configuration

Avant d’afficher le composant UserMFAManagement, suivez les instructions de Build Account Security UI pour configurer votre tenant Auth0 et vos applications.

​

Activer les méthodes et les portées MFA

Activer les méthodes MFA

1. Accédez à Dashboard > Sécurité > Multi-factor Auth.
2. Activez les facteurs souhaités. Pour en savoir plus, consultez Multi-Factor Authentication Factors.

Configurer les permissions de My Account API

Configurez les permissions d’accès délégué par l’utilisateur de My Account API en suivant les instructions de Build Account Security UI. Les cinq permissions sont requises pour le flux complet de gestion des méthodes d’authentification.

​

Installer le composant

pnpm

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form et @tanstack/react-query sont des dépendances pairs. La commande installe également la dépendance @auth0/universal-components-core, qui fournit des utilitaires partagés et l’intégration à Auth0.

​

Pour commencer

import { UserMFAManagement } from "@auth0/universal-components-react";

export function SecurityPage() {
  return <UserMFAManagement />;
}

• Les composants sont toujours importés à partir du point d’entrée racine @auth0/universal-components-react, quel que soit le framework.
• Seul le composant Auth0ComponentProvider utilise un sous-chemin propre au framework : /spa pour les applications React et /rwa pour les applications Next.js.

Exemple d’intégration complet

import React from "react";
import { UserMFAManagement } from "@auth0/universal-components-react";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: {
            title: "Two-Factor Authentication",
            description: "Manage the extra verification methods used to protect your account.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Next.js (RWA)

​

Exigences de configuration

Avant d’afficher le composant UserMFAManagement, suivez les instructions de Création d’une interface de sécurité du compte pour configurer votre tenant Auth0 et vos applications.

​

Activer les méthodes MFA et les scopes

Activer les méthodes MFA

1. Accédez à Dashboard > Sécurité > Multi-factor Auth.
2. Activez les facteurs souhaités. Pour en savoir plus, consultez Multi-Factor Authentication Factors.

Configurer les permissions de My Account API

Configurez les permissions d’accès délégué par l’utilisateur de My Account API dans Création d’une interface de sécurité du compte. Les cinq permissions sont nécessaires au flux complet de gestion des méthodes d’authentification.

​

Installer le composant

pnpm

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form et @tanstack/react-query sont des dépendances pairs. La commande installe également la dépendance @auth0/universal-components-core, qui fournit des utilitaires partagés et l’intégration à Auth0.

​

Premiers pas

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";

export default function SecurityPage() {
  return <UserMFAManagement />;
}

Exemple d’intégration complet

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";
import { analytics } from "@/lib/analytics";

export default function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

shadcn

​

Prérequis de configuration

Avant d’afficher le composant UserMFAManagement, suivez les instructions de Build Account Security UI pour configurer votre tenant Auth0 et vos applications.

​

Activer les méthodes MFA et les scopes

Activer les méthodes MFA

1. Accédez à Dashboard > Sécurité > Authentification multifacteur.
2. Activez les facteurs souhaités. Pour en savoir plus, consultez Multi-Factor Authentication Factors.

Configurer les permissions de My Account API

Configurez les permissions d’accès délégué par l’utilisateur de My Account API en suivant les instructions de Build Account Security UI. Les cinq permissions sont requises pour le flux complet de gestion des méthodes d’authentification.

​

Installer le composant

npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json

La commande d’installation ajoute le code source du composant dans src/components/auth0/my-account/, ainsi que toutes les dépendances d’interface utilisateur et la dépendance @auth0/universal-components-core, qui fournit des utilitaires partagés et l’intégration à Auth0.

​

Pour commencer

import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";

export function SecurityPage() {
  return <UserMFAManagement />;
}

Exemple d’intégration complet

import React from "react";
import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

​

Propriété

​

Propriétés d’affichage

Les propriétés d’affichage contrôlent la façon dont le composant s’affiche, sans modifier son comportement.

Propriété	Type	Par défaut	Description
hideHeader	boolean	false	Masque l’en-tête du composant (titre et description).
readOnly	boolean	false	Désactive toutes les actions de modification (inscription et suppression). Les facteurs sont affichés, mais ne peuvent être ni ajoutés ni supprimés.
showActiveOnly	boolean	false	Affiche uniquement les types de facteurs pour lesquels l’utilisateur possède au moins une inscription active. Les types de facteurs sans inscription sont masqués.
disableEnroll	boolean	false	Masque le bouton d’inscription pour tous les types de facteurs. Les utilisateurs peuvent tout de même supprimer les facteurs existants.
disableDelete	boolean	false	Masque le bouton de suppression dans toutes les lignes de facteurs inscrits. Les utilisateurs peuvent tout de même inscrire de nouveaux facteurs.
factorConfig	Partial <Record<MFAType, { visible?: boolean; enabled?: boolean }>>	{}	Visibilité et état d’activation par type de facteur.

factorConfig

Utilisez factorConfig pour afficher ou griser certains types de facteurs sans modifier la configuration du tenant. Chaque clé est une string correspondant à un type de facteur; les deux champs sont facultatifs et ont la valeur true par défaut.

Clés de types de facteurs prises en charge : phone, totp, email, push-notification, webauthn-platform, webauthn-roaming, recovery-code.

• visible affiche la ligne du facteur dans la liste (false pour la masquer).
• enabled rend la ligne du facteur interactive (false l’affiche grisée et non interactive).

<UserMFAManagement
  factorConfig={{
    phone: { visible: true, enabled: true },
    totp: { visible: true, enabled: true },
    email: { visible: true, enabled: false }, // affiché, mais grisé
    "webauthn-platform": { visible: false },  // complètement masqué
  }}
/>

​

Propriétés d’Action

Les propriétés d’Action permettent de s’intégrer aux événements du cycle de vie d’inscription et de suppression du composant, ainsi que de déclencher ou d’annuler des opérations.

Propriété	Type	Description
enrollAction	ComponentAction<MFAType>	Hooks du cycle de vie de l’inscription d’un facteur. Définissez disabled: true pour désactiver l’action d’inscription.
deleteAction	ComponentAction<MFAType>	Hooks du cycle de vie de la suppression d’un facteur. Définissez disabled: true pour désactiver l’action de suppression.

enrollAction

Utilisez onBefore pour annuler l’inscription avant le début du flow. Utilisez onAfter pour actualiser l’interface utilisateur associée ou envoyer des données analytiques une fois l’inscription réussie.

<UserMFAManagement
  enrollAction={{
    onBefore: (factor) => window.confirm(`Enroll ${factor}?`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Enrolled", { factor });
    },
  }}
/>

deleteAction

Utilisez onBefore pour annuler la suppression avant que la boîte de dialogue de confirmation intégrée s’affiche. onAfter s’exécute après la suppression réussie d’un facteur.

<UserMFAManagement
  deleteAction={{
    onBefore: (factor) =>
      window.confirm(`Remove your ${factor} authenticator? You may be locked out if this is your only factor.`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Deleted", { factor });
    },
  }}
/>

​

Personnaliser les propriétés

Les propriétés de personnalisation vous permettent d’adapter le texte, les règles de validation et le style sans modifier le code source.

Propriété	Type	Description
customMessages	Partial<UserMfaManagementMessages>	Remplace le texte et les traductions par défaut de l’interface utilisateur.
styling	ComponentStyling<UserMFAManagementClasses>	Variables CSS et remplacements de classes.
schema	{ email?: RegExp; phone?: RegExp }	Modèles de validation personnalisés pour les champs de saisie d’adresse courriel et de numéro de téléphone.

customMessages

Personnalisez tous les textes et toutes les traductions. Chaque champ est facultatif.

Messages disponibles

En-tête header.title, header.description, no_active_mfa, loading_text, component_error.title, component_error.description

Actions actions.remove_button_label, actions.cancel_button_label, actions.confirm_button_label, actions.continue_button_label, actions.submit_button_label, actions.verify_button_label, actions.back_button_label, actions.deleting_button_text, actions.menu_aria_label

Par type de facteur (remplacez {factor} par phone, totp, email, push-notification, webauthn-platform, webauthn-roaming ou recovery-code) factors.{factor}.title, factors.{factor}.description, factors.{factor}.button_text

Inscription et suppression enrollment et remove_factor_dialog

<UserMFAManagement
  customMessages={{
    header: {
      title: "Two-Factor Authentication",
      description: "Add extra layers of security to protect your account.",
    },
    no_active_mfa: "You haven't enrolled any authentication methods yet.",
    factors: {
      phone: {
        title: "Text message (SMS)",
        description: "Receive a one-time code via text message.",
        button_text: "Add method",
      },
      totp: {
        title: "Authenticator app",
        description: "Use Google Authenticator, Authy, or any TOTP app.",
      },
    },
    notifications: {
      fetch_factors_error: "Unable to load your security methods.",
    },
  }}
/>

Personnaliser le style

Personnalisez l’apparence à l’aide de variables CSS et de surcharges de classes. Prend en charge les thèmes clair et sombre.

Options de style disponibles

Variables—propriétés CSS personnalisées

• common S’applique aux deux thèmes
• light Mode clair seulement
• dark Mode sombre seulement

Surcharges de classes

• UserMFAManagement-item conteneur de chaque carte de type de facteur
• EnrollFactorModal-dialogContent zone de contenu de la boîte de dialogue d’inscription à plusieurs étapes
• FactorDeleteModal-dialogContent zone de contenu de la boîte de dialogue de confirmation de suppression

<UserMFAManagement
  styling={{
    variables: {
      light: { "--color-primary": "#4f46e5" },
      dark: { "--color-primary": "#818cf8" },
    },
    classes: {
      "UserMFAManagement-item": "rounded-2xl shadow-md border-2",
      "EnrollFactorModal-dialogContent": "max-w-lg",
      "FactorDeleteModal-dialogContent": "max-w-sm",
    },
  }}
/>

schema

Remplacez les motifs d’expression régulière intégrés utilisés pour valider les données saisies par l’utilisateur lors de l’inscription. Les deux champs sont facultatifs ; les champs non définis conservent leurs motifs par défaut.

• email valide l’adresse courriel saisie lors de l’inscription par OTP par courriel (par défaut : motif standard de type RFC 5322).
• phone valide le numéro de téléphone saisi lors de l’inscription par SMS (par défaut : accepte le format international E.164).

<UserMFAManagement
  schema={{
    // Limiter au domaine de l'entreprise uniquement
    email: /^[a-zA-Z0-9._%+-]+@example\.com$/,
    // Numéros américains uniquement
    phone: /^\+1[2-9]\d{2}[2-9]\d{6}$/,
  }}
/>

​

Définitions TypeScript

type MFAType =
  | "phone"
  | "totp"
  | "email"
  | "push-notification"
  | "webauthn-platform"
  | "webauthn-roaming"
  | "recovery-code";

interface FactorConfigOptions {
  visible?: boolean;
  enabled?: boolean;
}

interface UserMFAManagementClasses {
  "UserMFAManagement-item"?: string;
  "EnrollFactorModal-dialogContent"?: string;
  "FactorDeleteModal-dialogContent"?: string;
}

interface ComponentAction<Item, Context = void> {
  disabled?: boolean;
  onBefore?: (item: Item, context?: Context) => boolean;
  onAfter?: (item: Item, context?: Context) => void | boolean | Promise<boolean>;
}

interface UserMFAManagementProps {
  hideHeader?: boolean;
  showActiveOnly?: boolean;
  disableEnroll?: boolean;
  disableDelete?: boolean;
  readOnly?: boolean;
  factorConfig?: Partial<Record<MFAType, FactorConfigOptions>>;
  customMessages?: Partial<UserMfaManagementMessages>;
  styling?: ComponentStyling<UserMFAManagementClasses>;
  schema?: { email?: RegExp; phone?: RegExp };
  enrollAction?: ComponentAction<MFAType>;
  deleteAction?: ComponentAction<MFAType>;
}

​

Personnalisation avancée

En plus de la configuration du composant décrite ci-dessus, utilisez le hook useUserMFA pour créer une interface personnalisée de gestion de l’AMF.

import { useUserMFA } from "@auth0/universal-components-react";

export function CustomMfaManagement() {
  const {
    factorsByType,
    isLoadingFactors,
    error,
    visibleFactorTypes,
    handleEnroll,
    handleDeleteFactor,
  } = useUserMFA({
    factorConfig: {
      phone: { visible: true, enabled: true },
      totp: { visible: true, enabled: true },
    },
  });

  if (isLoadingFactors) return <p>Loading authentication methods…</p>;
  if (error) return <p role="alert">{error}</p>;

  return (
    <ul>
      {visibleFactorTypes.map((factorType) => (
        <li key={factorType}>
          <button onClick={() => handleEnroll(factorType)}>
            Add {factorType}
          </button>
          {factorsByType[factorType]?.map((factor) => (
            <button
              key={factor.id}
              onClick={() => handleDeleteFactor(factor.id, factorType)}
            >
              Remove {factorType}
            </button>
          ))}
        </li>
      ))}
    </ul>
  );
}

Le hook accepte showActiveOnly, readOnly, disableDelete, factorConfig, customMessages, enrollAction et deleteAction. Il renvoie les données des facteurs, l’état du chargement et des actions, l’état de l’inscription et de la suppression, ainsi que les gestionnaires nécessaires pour mettre en œuvre les flux d’inscription, de vérification et de suppression.

Utilisez UserMFAManagement si vous souhaitez utiliser l’interface intégrée. Si vous utilisez le hook, mettez en œuvre l’interface utilisateur correspondante pour l’inscription, la vérification, les codes de récupération et la suppression des types de facteurs que vous prenez en charge.

onAfter dans enrollAction et deleteAction s’exécute lorsque la notification de réussite se ferme, plutôt qu’immédiatement après la fin de l’action.

​

En savoir plus

Gestion des clés d’accès des utilisateurs

Gérez les clés d’accès WebAuthn selon le même cycle de vie.

Créer une interface libre-service de sécurité du compte

Aperçu, prérequis et configuration du framework pour tous les composants My Account.