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

Affichez une interface utilisateur sous forme de cartes permettant aux utilisateurs d’enregistrer et de révoquer leurs propres clés d’accès WebAuthn au moyen de l’API My Account d’Auth0.

Le composant UserPasskeyManagement permet aux utilisateurs d’inscrire et de révoquer des clés d’accès dans une interface unique sous forme de carte, à l’aide de l’API My Account, sans nécessiter de props pour le rendu. Le composant affiche une liste des clés d’accès inscrites, un bouton pour en ajouter une et une option permettant de les révoquer.

​

Prérequis

Pour activer la prise en charge des clés d’accès :

• Configurez un domaine personnalisé pour votre tenant Auth0. Les clés d’accès nécessitent un domaine personnalisé.

• Activez les clés d’accès pour votre connexion à une base de données Auth0. Pour savoir comment activer les clés d’accès dans votre tenant Auth0, consultez Configurer les clés d’accès.

• Faites correspondre l’origine. L’ID de la partie utilisatrice doit correspondre au domaine de votre application ou à un domaine parent enregistrable de celui-ci. Pour en savoir plus, consultez ID de partie utilisatrice pour les clés d’accès

• Assurez-vous que votre application utilise HTTPS. WebAuthn exige que votre application soit accessible en HTTPS.

• Installez et configurez Universal Components dans votre application. Pour installer et configurer Universal Components, consultez Créer une interface utilisateur de sécurité du compte.

​

Configurez votre application

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

React (SPA)

​

Installez 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 { UserPasskeyManagement } from "@auth0/universal-components-react";

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

• Les composants sont toujours importés depuis le point d’entrée racine @auth0/universal-components-react, quel que soit le framework utilisé.
• 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 { UserPasskeyManagement } 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">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onBefore: (passkey) =>
            window.confirm(`Remove passkey "${passkey.name}"?`),
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        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)

​

Installez 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

app/security/passkeys/page.tsx

"use client";

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

export default function PasskeysPage() {
  return <UserPasskeyManagement />;
}

Exemple d’intégration complet

app/security/passkeys/page.tsx

"use client";

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

export default function PasskeysPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

shadcn

​

Installer le composant

npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-passkey-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 { UserPasskeyManagement } from "@/components/auth0/my-account/user-passkey-management";

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

Exemple d’intégration complet

import React from "react";
import { UserPasskeyManagement } from "@/components/auth0/my-account/user-passkey-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">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onBefore: (passkey) =>
            window.confirm(`Remove passkey "${passkey.name}"?`),
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        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>
  );
}

​

Props

​

Props d’affichage

Les props d’affichage déterminent la façon dont le composant s’affiche, sans modifier son comportement.

Prop	Type	Par défaut	Description
hideHeader	boolean	false	Masque l’en-tête de la page (le titre et la description). La carte de section contenant la liste des clés d’accès est toujours affichée.

​

Props d’Action

Les props d’Action permettent de vous accrocher aux événements du cycle de vie du composant et de déclencher ou d’annuler des opérations.

Prop	Type	Description
addAction	ComponentAction<void>	Hooks de cycle de vie du flux d’ajout d’une clé d’accès. Définissez disabled: true pour masquer le bouton d’ajout.
revokeAction	ComponentAction<Passkey>	Hooks de cycle de vie du flux de révocation d’une clé d’accès. Définissez disabled: true pour masquer l’option de révocation.
onFetch	() => void	Déclenché une fois la liste des clés d’accès chargée avec succès.

addAction

Contrôle le flux d’ajout d’une clé d’accès. onBefore se déclenche avant l’affichage de l’invite WebAuthn du navigateur; retournez false pour annuler (par exemple, afin d’imposer une limite de clés d’accès). onAfter se déclenche une fois la nouvelle clé d’accès enregistrée.

• disabled masque le bouton “Ajouter une clé d’accès”.
• onBefore() s’exécute avant la procédure d’enrôlement WebAuthn. Retournez false pour annuler.
• onAfter() s’exécute une fois la clé d’accès enregistrée avec succès. Utilisez-le pour actualiser l’état de la session ou envoyer des données analytiques.

<UserPasskeyManagement
  addAction={{
    onBefore: () => {
      if (passkeys.length >= 5) {
        toast.error("You can register a maximum of 5 passkeys.");
        return false;
      }
      return true;
    },
    onAfter: () => {
      analytics.track("Passkey Enrolled");
    },
  }}
/>

revokeAction

Contrôle le flux de révocation d’une clé d’accès. onBefore s’exécute avant l’affichage de la boîte de dialogue de confirmation intégrée; vous pouvez donc annuler le flux avant que l’utilisateur ne la voie. onAfter se déclenche après la suppression de la clé d’accès du compte.

• disabled masque l’option de révocation dans le menu d’actions de la clé d’accès.
• onBefore(passkey) s’exécute avant l’appel d’API de révocation. Reçoit l’objet Passkey. Retournez false pour annuler.
• onAfter(passkey) s’exécute après la révocation réussie de la clé d’accès. Reçoit l’objet Passkey révoqué.

<UserPasskeyManagement
  revokeAction={{
    onAfter: (passkey) => {
      auditLog.record({ action: "passkey_revoked", passkeyId: passkey.id });
    },
  }}
/>

onFetch

Se déclenche une fois la liste des clés d’accès chargée au montage. Utilisez cette fonction pour afficher ou masquer les éléments d’UI adjacents selon que l’utilisateur possède ou non des clés d’accès enregistrées.

<UserPasskeyManagement
  onFetch={() => {
    setPasskeysLoaded(true);
  }}
/>

Pour rendre la liste en lecture seule, définissez disabled: true sur les deux actions :

<UserPasskeyManagement
  addAction={{ disabled: true }}
  revokeAction={{ disabled: true }}
/>

​

Personnaliser les props

Les props de personnalisation vous permettent d’adapter le texte et le style sans modifier le code source.

Prop	Type	Description
customMessages	Partial<UserPasskeyManagementMessages>	Remplace le texte et les traductions par défaut de l’interface utilisateur.
styling	ComponentStyling<UserPasskeyManagementClasses>	Variables CSS et surcharges de classes.

customMessages

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

Messages disponibles

• header—title, description (en-tête de page; masqué lorsque hideHeader est défini sur true)
• Carte principale—section_title, enabled (badge affiché lorsque des clés d’accès sont enregistrées), no_passkeys (message d’état vide), add_passkey (libellé du bouton d’ajout)
• Éléments de la liste—created_at (utilisez ${date} comme espace réservé), last_used (utilisez ${date} comme espace réservé)
• Actions—actions.revoke (libellé du menu d’actions associé à chaque clé d’accès)
• Notifications de réussite—success.add, success.revoke
• Fenêtre modale de révocation—modals.revoke.title, modals.revoke.consent (utilisez <bold>${name}</bold> pour mettre en gras le nom de la clé d’accès), modals.revoke.cancel, modals.revoke.confirm

<UserPasskeyManagement
  customMessages={{
    header: {
      title: "Passkeys",
      description: "Sign in faster and more securely without a password.",
    },
    section_title: "Your passkeys",
    no_passkeys: "No passkeys registered yet.",
    add_passkey: "Add a passkey",
    created_at: "Added ${date}",
    last_used: "Last used ${date}",
    success: {
      add: "Passkey registered successfully.",
      revoke: "Passkey removed.",
    },
    modals: {
      revoke: {
        title: "Remove passkey?",
        consent: "This will permanently remove <bold>${name}</bold>.",
        cancel: "Cancel",
        confirm: "Remove",
      },
    },
  }}
/>

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’appliquent aux deux thèmes
• light Mode clair uniquement
• dark Mode sombre uniquement

Surcharges de classes

• UserPasskeyManagement-root le conteneur de carte externe qui contient la liste des clés d’accès
• UserPasskeyManagement-item chaque carte de ligne de clé d’accès
• PasskeyActionModal-modalContent la zone de contenu de la fenêtre modale de confirmation de révocation

<UserPasskeyManagement
  styling={{
    variables: {
      light: { "--color-primary": "#4f46e5" },
      dark: { "--color-primary": "#818cf8" },
    },
    classes: {
      "UserPasskeyManagement-root": "rounded-2xl shadow-md",
      "UserPasskeyManagement-item": "rounded-xl border border-gray-200",
      "PasskeyActionModal-modalContent": "max-w-sm",
    },
  }}
/>

​

Définitions TypeScript

interface Passkey {
  id: string;
  name?: string;
  createdAt?: string;
  lastUsedAt?: string;
  deviceInfo?: string;
}

interface UserPasskeyManagementClasses {
  "UserPasskeyManagement-root"?: string;
  "UserPasskeyManagement-item"?: string;
  "PasskeyActionModal-modalContent"?: string;
}

// ComponentAction fournit des hooks avant/après ainsi qu'un flag de désactivation.
// Les deux hooks reçoivent le même type de données T.
interface ComponentAction<Item, Context = void> {
  disabled?: boolean;
  onBefore?: (item: Item, context?: Context) => boolean;
  onAfter?: (item: Item, context?: Context) => void | boolean | Promise<boolean>;
}

interface UserPasskeyManagementProps {
  hideHeader?: boolean;
  customMessages?: Partial<UserPasskeyManagementMessages>;
  styling?: ComponentStyling<UserPasskeyManagementClasses>;
  addAction?: ComponentAction<void>;
  revokeAction?: ComponentAction<Passkey>;
  onFetch?: () => void;
}

​

Personnalisation avancée

En plus de la configuration du composant décrite ci-dessus, utilisez le hook useUserPasskey pour créer une interface personnalisée de gestion des clés d’accès.

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

export function CustomPasskeyManagement() {
  const {
    passkeys,
    isLoading,
    isEnrolling,
    isRevoking,
    disableAdd,
    disableRevoke,
    currentPasskey,
    isRevokeModalOpen,
    setIsRevokeModalOpen,
    handleAddPasskey,
    handleRevokePasskey,
    handleConfirmRevoke,
  } = useUserPasskey({});

  if (isLoading) return <p>Loading passkeys…</p>;

  return (
    <>
      <button disabled={disableAdd || isEnrolling} onClick={handleAddPasskey}>
        Add passkey
      </button>

      <ul>
        {passkeys.map((passkey) => (
          <li key={passkey.id}>
            {passkey.name ?? "Unnamed passkey"}
            <button
              disabled={disableRevoke || isRevoking}
              onClick={() => handleRevokePasskey(passkey)}
            >
              Remove
            </button>
          </li>
        ))}
      </ul>

      {isRevokeModalOpen && currentPasskey && (
        <div role="dialog" aria-modal="true">
          <p>Remove {currentPasskey.name ?? "passkey"}?</p>
          <button disabled={isRevoking} onClick={handleConfirmRevoke}>
            Confirm removal
          </button>
          <button onClick={() => setIsRevokeModalOpen(false)}>Cancel</button>
        </div>
      )}
    </>
  );
}

Le hook accepte customMessages, addAction, revokeAction et onFetch. Il renvoie les données de clé d’accès, l’état de chargement et des actions, la cible de révocation active, ainsi que les gestionnaires d’inscription et de révocation de clé d’accès.

Utilisez UserPasskeyManagement si vous souhaitez utiliser l’interface intégrée. Si vous utilisez le hook, implémentez l’interface utilisateur de confirmation de révocation correspondante et son comportement de fermeture.

​

En savoir plus

Gestion des facteurs MFA des utilisateurs

Gérez les facteurs MFA (TOTP, SMS, OTP par courriel, push, codes de récupération) ainsi que les clés d’accès.

Créer une interface de sécurité des comptes en libre-service

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