Clés d’accès avec plusieurs domaines personnalisés

Découvrez comment les clés d’accès et WebAuthn s’utilisent avec plusieurs domaines personnalisés dans Auth0.

Les clés d’accès offrent une expérience d’authentification sans mot de passe résistante à l’hameçonnage grâce à WebAuthn. Lorsque vous utilisez plusieurs domaines personnalisés, les clés d’accès sont inscrites pour chaque domaine en raison du modèle de sécurité de WebAuthn.

​

Fonctionnement des clés d’accès avec les domaines personnalisés

​

Identifiant de partie de confiance WebAuthn (RP ID)

WebAuthn utilise un identifiant de partie de confiance (RP ID) pour définir la portée des identifiants de clé d’accès. Le RP ID détermine :

• Où les clés d’accès peuvent être utilisées : les clés d’accès sont liées au domaine où elles ont été créées
• Limites de sécurité : empêche l’utilisation des clés d’accès sur des domaines non autorisés
• Expérience utilisateur : les utilisateurs doivent inscrire leurs clés d’accès séparément pour chaque domaine personnalisé

​

Inscription par domaine

Avec plusieurs domaines personnalisés, chaque domaine possède son propre RP ID, ce qui signifie :

• Une clé d’accès inscrite sur login.brand1.com ne peut pas être utilisée sur login.brand2.com
• Les utilisateurs qui s’authentifient au moyen de différents domaines personnalisés doivent inscrire des clés d’accès pour chaque domaine
• Les clés d’accès de chaque domaine sont gérées indépendamment

​

Comprendre l’expérience utilisateur liée aux clés d’accès

​

Une seule marque, un seul domaine

Configuration : Un domaine personnalisé pour une seule marque

Expérience utilisateur :

1. L’utilisateur accède à login.example.com
2. L’utilisateur inscrit une clé d’accès
3. L’utilisateur peut utiliser la clé d’accès pour toutes ses prochaines connexions via login.example.com

Complexité : Faible - expérience simple et directe avec les clés d’accès

​

Marques multiples, domaines distincts

Configuration: Plusieurs marques, chacune avec son propre domaine personnalisé

Expérience utilisateur:

1. L’utilisateur visite login.brand1.com et inscrit une clé d’accès
2. Le même utilisateur se rend ensuite sur login.brand2.com (marque différente)
3. La clé d’accès précédemment inscrite n’est pas disponible
4. L’utilisateur doit inscrire une nouvelle clé d’accès pour login.brand2.com

Complexité: Moyenne - les utilisateurs ont besoin de clés d’accès distinctes pour chaque marque

Bonne pratique: Indiquez aux utilisateurs que chaque marque exige l’inscription d’une clé d’accès distincte

​

Configuration multilocataire avec domaine commun

Configuration : Plusieurs clients avec un domaine personnalisé commun pour les services partagés.

Expérience utilisateur :

1. La plupart des utilisateurs s’authentifient par le domaine commun
2. Les utilisateurs inscrivent leurs clés d’accès une seule fois pour le domaine commun
3. Les clés d’accès fonctionnent de façon uniforme dans la plupart des scénarios d’authentification
4. Les cas particuliers (domaines propres à chaque client) nécessitent une inscription distincte

Complexité : Faible à moyenne — la plupart des utilisateurs ont une expérience uniforme

​

Configuration

​

Activer les clés d’accès pour votre locataire

Avant d’utiliser des clés d’accès avec des domaines personnalisés, assurez-vous qu’elles sont activées :

1. Accédez à Auth0 Dashboard > Security > Multi-factor Auth
2. Activez WebAuthn with FIDO Security Keys
3. Configurez les paramètres des clés d’accès

​

Configurer des domaines personnalisés pour les clés d’accès

Chaque domaine personnalisé obtient automatiquement son propre RP ID :

• Format du RP ID : le domaine personnalisé lui-même (p. ex., login.example.com)
• Aucune configuration supplémentaire n’est requise : Auth0 configure automatiquement le RP ID pour chaque domaine personnalisé vérifié

​

Vérifier la configuration du RP ID

Pour vérifier le RP ID d’un domaine personnalisé :

1. Accédez à Auth0 Dashboard > Image de marque > Domaines personnalisés
2. Sélectionnez votre domaine personnalisé
3. Dans les détails du domaine, le RP ID s’affiche

​

Modèles d’implémentation

​

Inviter à inscrire des clés d’accès par domaine

Invitez les utilisateurs à inscrire des clés d’accès pour chaque domaine personnalisé qu’ils utilisent :

import { createAuth0Client } from '@auth0/auth0-spa-js';

async function setupPasskeyEnrollment() {
  const auth0 = await createAuth0Client({
    domain: 'login.example.com',
    clientId: 'YOUR_CLIENT_ID'
  });

  // Vérifier si l'utilisateur est authentifié
  const isAuthenticated = await auth0.isAuthenticated();

  if (isAuthenticated) {
    // Vérifier si la clé d'accès est inscrite pour ce domaine
    const user = await auth0.getUser();

    if (!user.passkey_enrolled) {
      // Inviter l'utilisateur à inscrire une clé d'accès
      showPasskeyEnrollmentPrompt();
    }
  }
}

function showPasskeyEnrollmentPrompt() {
  // Afficher l'interface pour encourager l'inscription d'une clé d'accès
  const banner = document.createElement('div');
  banner.innerHTML = `
    <div class="passkey-prompt">
      <p>Set up passkey for faster, more secure login on this site</p>
      <button onclick="enrollPasskey()">Set Up Passkey</button>
    </div>
  `;
  document.body.prepend(banner);
}

​

Suivre l’inscription des clés d’accès par domaine

Enregistrez les domaines pour lesquels un utilisateur a inscrit des clés d’accès :

// Dans votre Auth0 Action (Post-Login)
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;
  const authMethods = event.authentication?.methods || [];

  // Vérifier si l'utilisateur s'est authentifié avec une clé d'accès
  const usedPasskey = authMethods.some(method =>
    method.name === 'webauthn' || method.name === 'passkey'
  );

  if (usedPasskey) {
    // Suivre les domaines pour lesquels l'utilisateur a inscrit des clés d'accès
    const enrolledDomains = event.user.app_metadata?.passkey_domains || [];

    if (domain && !enrolledDomains.includes(domain)) {
      enrolledDomains.push(domain);
      api.user.setAppMetadata('passkey_domains', enrolledDomains);
    }

    // Ajouter une revendication au jeton
    api.idToken.setCustomClaim('passkey_enrolled', true);
    api.idToken.setCustomClaim('passkey_domain', domain);
  } else {
    // L'utilisateur n'a pas utilisé de clé d'accès
    api.idToken.setCustomClaim('passkey_enrolled', false);
  }
};

Ensuite, dans votre application :

async function checkPasskeyEnrollment() {
  const auth0 = await createAuth0Client({
    domain: window.CUSTOM_DOMAIN,
    clientId: 'YOUR_CLIENT_ID'
  });

  const isAuthenticated = await auth0.isAuthenticated();

  if (isAuthenticated) {
    const user = await auth0.getUser();
    const claims = await auth0.getIdTokenClaims();

    // Vérifier si la clé d'accès est inscrite pour le domaine actuel
    const passkeyEnrolledHere = claims.passkey_enrolled &&
                                 claims.passkey_domain === window.CUSTOM_DOMAIN;

    if (!passkeyEnrolledHere) {
      // Inviter l'utilisateur à inscrire une clé d'accès pour ce domaine
      promptPasskeyEnrollment();
    }
  }
}

​

Pages d’inscription propres à chaque domaine

Créez des pages d’inscription distinctes pour chaque domaine personnalisé :

// Page d'inscription pour la marque 1
// URL: https://login.brand1.com/enroll-passkey

import { createAuth0Client } from '@auth0/auth0-spa-js';

async function enrollPasskeyForBrand1() {
  const auth0 = await createAuth0Client({
    domain: 'login.brand1.com',
    clientId: 'YOUR_CLIENT_ID'
  });

  try {
    // Déclencher l'inscription de la clé d'accès
    await auth0.loginWithPopup({
      authorizationParams: {
        acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor',
        prompt: 'login'
      }
    });

    alert('Passkey enrolled successfully for Brand 1!');
  } catch (error) {
    console.error('Passkey enrollment failed:', error);
  }
}

​

Invites d’inscription contextuelles

Affichez des invites d’inscription aux clés d’accès en fonction du comportement de l’utilisateur. Points à considérer :

• Suivez les cas où les utilisateurs ignorent les invites d’inscription (stockez-les dans localStorage)
• Vérifiez logins_count dans les métadonnées de l’utilisateur pour afficher les invites après plusieurs visites
• Vérifiez qu’aucune clé d’accès n’est déjà inscrite pour le domaine actuel

async function shouldShowEnrollmentPrompt(auth0, customDomain) {
  const storageKey = `passkey_prompt_dismissed_${customDomain}`;

  // Ne pas afficher si l'utilisateur l'a ignoré
  if (localStorage.getItem(storageKey)) return false;

  const claims = await auth0.getIdTokenClaims();
  const passkeyEnrolled = claims.passkey_enrolled &&
                          claims.passkey_domain === customDomain;

  if (passkeyEnrolled) return false;

  // Afficher l'invite après la 3e connexion
  const user = await auth0.getUser();
  return (user.logins_count || 0) >= 3;
}

​

Communication aux utilisateurs

​

Informer les utilisateurs de l’inscription propre à chaque domaine

Communiquez clairement aux utilisateurs que les clés d’accès sont associées à un domaine précis :

Exemple de message :

“Pour des raisons de sécurité, les clés d’accès sont propres à chaque portail de connexion. Vous devrez configurer une clé d’accès distincte pour la page de connexion de chaque marque que vous utilisez.”

Exemple d’invite d’inscription :

<div class="passkey-info-banner">
  <h3>Set up faster login with passkey</h3>
  <p>
    This passkey will work for login.example.com.
    If you use other login portals, you'll need to set up passkeys separately for each one.
  </p>
  <button onclick="enrollPasskey()">Set Up Passkey</button>
  <button onclick="dismissPrompt()">Not Now</button>
</div>

​

Documentation d’aide

Fournissez une documentation d’aide claire :

Exemple d’entrée de FAQ :

Q : Pourquoi dois-je configurer une clé d’accès à nouveau ?

R : Pour des raisons de sécurité, les clés d’accès sont associées à des domaines précis. Si vous vous connectez par l’intermédiaire d’un portail différent (p. ex., Marque A vs Marque B), vous devrez configurer une clé d’accès pour chacun d’eux. Cela protège vos comptes en garantissant que les clés d’accès ne fonctionnent que sur les domaines prévus.

Q : Ai-je besoin d’un appareil différent pour chaque clé d’accès ?

R : Non ! Vous pouvez utiliser le même appareil (téléphone, ordinateur ou clé matérielle) pour des clés d’accès sur différents domaines. Chaque clé d’accès est simplement un justificatif d’authentification distinct stocké sur votre appareil.

​

Limites et considérations

​

Limitations actuelles

Limitation	Impact	Solution de contournement
Aucun partage de clés d’accès entre domaines	Les utilisateurs doivent inscrire des clés d’accès séparément pour chaque domaine personnalisé	Utilisez un domaine commun pour la majorité des authentifications, ou guidez les utilisateurs pour qu’ils s’inscrivent sur chaque domaine
Impossible de transférer des clés d’accès entre domaines	La migration vers un nouveau domaine personnalisé nécessite une nouvelle inscription	Planifiez la migration avec soin, communiquez avec les utilisateurs et prévoyez un flux de nouvelle inscription
Origines associées non encore prises en charge	Impossible de partager des clés d’accès entre des sous-domaines ou des domaines associés	Prévu dans une version ultérieure - utilisez pour l’instant l’inscription par domaine

​

Origines associées (fonctionnalité à venir)

Auth0 prévoit de prendre en charge les origines associées WebAuthn, ce qui permettra le partage de clés d’accès entre des domaines précis. Cette fonctionnalité :

• Vous permettra de configurer des domaines comme « associés » pour les clés d’accès
• Permettra aux utilisateurs d’utiliser une clé d’accès inscrite sur login.brand1.com sur login.brand2.com si ces domaines sont configurés comme associés
• Offrira plus de souplesse pour les implémentations multimarques

Statut : Prévu pour une version ultérieure à la GA

​

Scénarios de migration

​

Migration d’un domaine personnalisé unique vers plusieurs

Avant : Domaine personnalisé unique avec des clés d’accès déjà inscrites

Après : Plusieurs domaines personnalisés pour différentes marques

Défi : Les clés d’accès existantes ne fonctionnent que sur le domaine d’origine

Approche de migration :

1. Conserver le domaine d’origine actif : Maintenez le domaine personnalisé d’origine comme domaine commun
2. Déploiement progressif : Introduisez progressivement de nouveaux domaines personnalisés
3. Notification aux utilisateurs : Informez les utilisateurs qu’ils devront inscrire des clés d’accès sur les nouveaux domaines
4. Prévoir un parcours de réinscription : Facilitez la réinscription des clés d’accès sur les nouveaux domaines
5. Surveiller l’adoption : Suivez les taux d’inscription aux clés d’accès par domaine

Modèle de communication :

« Nous lançons des pages de connexion propres à chaque marque ! Votre clé d’accès existante continuera de fonctionner sur [original domain]. Lorsque vous visiterez nos nouvelles pages de connexion, vous serez invité à configurer une clé d’accès pour vous y connecter plus rapidement. »

​

Migration d’un domaine personnalisé à un autre

Scénario : Passer de old-domain.com à new-domain.com

Défi : Les clés d’accès ne peuvent pas être transférées

Étapes de migration :

1. Fonctionnement en parallèle : Exécutez les deux domaines simultanément pendant la transition
2. Détecter les clés d’accès inscrites : Repérez quels utilisateurs ont des clés d’accès sur l’ancien domaine
3. Inviter à se réinscrire : Lorsque les utilisateurs se connectent au moyen du nouveau domaine, invitez-les à inscrire une clé d’accès
4. Période de grâce : Gardez l’ancien domaine actif pendant une période de transition
5. Retirer l’ancien domaine : Une fois la migration adoptée, mettez l’ancien domaine hors service

// Dans votre Action Auth0
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;
  const oldDomain = 'old-domain.com';
  const newDomain = 'new-domain.com';

  // Vérifier si l'utilisateur avait une clé d'accès sur l'ancien domaine
  const hadOldPasskey = event.user.app_metadata?.passkey_domains?.includes(oldDomain);

  // L'utilisateur est sur le nouveau domaine mais n'a pas encore de clé d'accès inscrite
  if (domain === newDomain && hadOldPasskey) {
    const newDomainPasskeys = event.user.app_metadata?.passkey_domains?.includes(newDomain);

    if (!newDomainPasskeys) {
      // Définir un indicateur pour inviter à la réinscription
      api.idToken.setCustomClaim('should_enroll_passkey', true);
      api.idToken.setCustomClaim('migrated_from', oldDomain);
    }
  }
};

​

Tests

​

Tester l’inscription des clés d’accès pour chaque domaine

1. Configurer des domaines personnalisés de test : Configurez plusieurs domaines personnalisés dans un locataire de développement
2. Tester le flux d’inscription : Inscrivez une clé d’accès via un domaine personnalisé
3. Vérifier l’isolation : Confirmez que la clé d’accès ne fonctionne pas sur les autres domaines personnalisés
4. Tester la réinscription : Inscrivez des clés d’accès sur d’autres domaines
5. Tests sur plusieurs navigateurs : Testez sur différents navigateurs et appareils

​

Tests automatisés

describe('Passkey Enrollment with Multiple Custom Domains', () => {
  it('should enroll passkey on domain 1', async () => {
    await navigateTo('https://login.brand1.com');
    await login();
    await enrollPasskey();
    expect(await isPasskeyEnrolled()).toBe(true);
  });

  it('should not have passkey on domain 2', async () => {
    await navigateTo('https://login.brand2.com');
    await login();
    expect(await isPasskeyEnrolled()).toBe(false);
  });

  it('should enroll separate passkey on domain 2', async () => {
    await navigateTo('https://login.brand2.com');
    await login();
    await enrollPasskey();
    expect(await isPasskeyEnrolled()).toBe(true);
  });
});

​

Bonnes pratiques

1. Utilisez un domaine commun : Utilisez un domaine personnalisé commun pour réduire le nombre de domaines nécessitant l’inscription de clés d’accès
2. Communication claire : Informez les utilisateurs des exigences d’inscription propres à chaque domaine
3. Présentez les invites de façon stratégique : Affichez les invites d’inscription après que les utilisateurs ont démontré un certain engagement (p. ex., 3 connexions ou plus)
4. Suivez les inscriptions : Surveillez quels utilisateurs ont inscrit des clés d’accès sur quels domaines
5. Offrez de l’aide : Fournissez une documentation claire et une assistance pour la gestion des clés d’accès
6. Testez de façon approfondie : Testez les flux de clés d’accès sur tous les domaines personnalisés avant le déploiement en production
7. Planifiez les migrations : Lorsque vous modifiez des domaines personnalisés, prévoyez la réinscription des utilisateurs
8. Surveillez l’adoption : Suivez les taux d’inscription et d’utilisation des clés d’accès par domaine

​

Dépannage

​

La clé d’accès ne fonctionne pas sur un domaine personnalisé

Symptômes : L’utilisateur a inscrit une clé d’accès, mais ne peut pas l’utiliser

Causes possibles :

• L’utilisateur est sur un domaine personnalisé différent de celui sur lequel il a inscrit sa clé d’accès
• Problèmes de compatibilité du navigateur
• La clé d’accès a été supprimée de l’appareil

Résolution :

1. Confirmez que l’utilisateur est sur le bon domaine personnalisé
2. Vérifiez la prise en charge de WebAuthn par le navigateur
3. Guidez l’utilisateur pour qu’il inscrive de nouveau sa clé d’accès, au besoin

​

Utilisateur dérouté par plusieurs inscriptions

Symptômes : L’utilisateur signale que « la clé d’accès ne fonctionne pas » lorsqu’il change de domaine

Cause : L’utilisateur ne comprend pas que l’inscription se fait par domaine

Résolution :

1. Fournir un message clair sur les clés d’accès propres à chaque domaine
2. Indiquer pour quels domaines l’utilisateur a inscrit des clés d’accès
3. Inviter l’utilisateur à inscrire une clé d’accès lorsqu’il visite un nouveau domaine

​

En savoir plus

• Domaines personnalisés multiples
• Spécification WebAuthn
• Passkeys.dev