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

Découvrez comment les clés d’accès et WebAuthn fonctionnent 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. Lorsqu’on utilise plusieurs domaines personnalisés, les clés d’accès sont enregistrées pour chaque domaine en raison du modèle de sécurité de WebAuthn.

​

Comment les clés d’accès fonctionnent avec les domaines personnalisés

​

ID 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 associées au domaine où elles ont été créées
• Les limites de sécurité : empêche l’utilisation de clés d’accès sur des domaines non autorisés
• L’expérience utilisateur : les utilisateurs doivent enregistrer des clés d’accès séparément pour chaque domaine personnalisé

​

Inscription par domaine

Avec plusieurs domaines personnalisés, chaque domaine a 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 par l’intermédiaire de différents domaines personnalisés doivent enrôler une clé d’accès pour chaque domaine
• Les clés d’accès de chaque domaine sont gérées de façon indépendante

​

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

​

Une seule image de marque, un seul domaine

Configuration : Un domaine personnalisé pour une image de marque

Expérience utilisateur :

1. L’utilisateur visite login.example.com
2. L’utilisateur enregistre une clé d’accès
3. L’utilisateur peut utiliser cette clé d’accès pour toutes les connexions futures via login.example.com

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

​

Plusieurs images de marque, domaines distincts

Configuration : Plusieurs images de marque, chacune avec son propre domaine personnalisé

Expérience utilisateur :

1. L’utilisateur visite login.brand1.com et enregistre une clé d’accès
2. Le même utilisateur visite plus tard login.brand2.com (image de marque différente)
3. La clé d’accès enregistrée précédemment n’est pas disponible
4. L’utilisateur doit enregistrer 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 image de marque

Bonne pratique : Indiquez aux utilisateurs que chaque image de marque nécessite l’enrôlement distinct d’une clé d’accès

​

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 au moyen du domaine commun
2. Les utilisateurs n’inscrivent leurs clés d’accès qu’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 à certains clients) nécessitent une inscription distincte

Complexité : Faible à moyenne - la plupart des utilisateurs profitent d’une expérience uniforme

​

Configuration

​

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

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 > Sécurité > Authentification multifacteur
2. Activez WebAuthn avec 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é se voit automatiquement attribuer 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 > Branding > Custom Domains
2. Sélectionnez votre domaine personnalisé
3. Dans les détails du domaine, le RP ID s’affiche

​

Modèles de mise en œuvre

​

Inciter à l’enrôlement de clés d’accès par domaine

Invitez les utilisateurs à enrôler 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’enrôlement des clés d’accès par domaine

Enregistrez les domaines pour lesquels un utilisateur a enregistré 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 enregistré 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 un claim 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’enrôlement par domaine

Créez des pages d’enrôlement dédiées 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 contextuelles d’enrôlement de clé d’accès

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

• Faites le suivi du moment où les utilisateurs ferment les invites d’enrôlement (stockez cette information dans localStorage)
• Vérifiez logins_count dans les métadonnées de l’utilisateur pour afficher les invites après plusieurs visites
• Vérifiez que la clé d’accès n’est pas déjà enrôlée pour le domaine actuel

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

  // Ne pas afficher si l'utilisateur l'a supprimé
  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

​

Informez les utilisateurs de l’enrôlement distincte pour chaque domaine

Indiquez clairement aux utilisateurs que les clés d’accès sont propres à chaque domaine :

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 séparément pour chaque page de connexion liée à une image de marque que vous utilisez.”

Exemple de prompt d’enrôlement :

<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 de nouveau ?

R : Les clés d’accès sont associés à des domaines précis pour des raisons de sécurité. Si vous ouvrez une session dans un portail différent (p. ex., Brand A ou Brand B), vous devrez configurer une clé d’accès pour chacun. Cela contribue à protéger vos comptes en garantissant que les clés d’accès ne fonctionnent que là où ils le doivent.

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 credential 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 enrôler des clés d’accès séparément pour chaque domaine personnalisé	Utilisez un domaine commun pour la plupart des flux d’authentification, ou guidez les utilisateurs pour qu’ils s’enrôlent sur chaque domaine
Impossible de transférer des clés d’accès d’un domaine à un autre	La migration vers un nouveau domaine personnalisé nécessite un nouvel enrôlement	Planifiez soigneusement la migration, communiquez avec les utilisateurs et prévoyez un flux d’enrôlement
Origines associées pas 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 prochaine version - utilisez pour l’instant un enrôlement par domaine

​

Origines associées (fonctionnalité à venir)

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

• Vous permettra de configurer des domaines comme « associés » aux fins des clés d’accès
• Permettra aux utilisateurs d’utiliser une clé d’accès enregistrée sur login.brand1.com sur login.brand2.com si ces domaines sont configurés comme associés
• Offrira plus de souplesse pour les mises en œuvre à marques multiples

Statut : Prévu après la disponibilité générale (GA)

​

Scénarios de migration

​

Migration d’un domaine personnalisé unique vers plusieurs

Avant : Un domaine personnalisé unique avec des clés d’accès enrôlées

Après : Plusieurs domaines personnalisés pour différentes images de marque

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

Approche de migration :

1. Garder le domaine d’origine actif : Conserver le domaine personnalisé d’origine comme domaine commun
2. Déploiement graduel : Introduire progressivement de nouveaux domaines personnalisés
3. Avis aux utilisateurs : Informer les utilisateurs qu’ils devront enrôler des clés d’accès sur les nouveaux domaines
4. Prévoir un processus de réenrôlement : Permettre aux utilisateurs d’enrôler facilement des clés d’accès sur les nouveaux domaines
5. Suivre l’adoption : Suivre les taux d’enrôlement des clés d’accès par domaine

Modèle de communication :

“Nous lançons des pages de connexion propres à chaque image de marque ! Votre clé d’accès actuelle continuera de fonctionner sur [original domain]. Lorsque vous visiterez nos nouvelles pages de connexion, on vous demandera de configurer une clé d’accès pour vous y connecter plus rapidement.”

​

Migration entre des domaines personnalisés

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

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

Étapes de migration :

1. Fonctionnement en parallèle : Utilisez les deux domaines simultanément pendant la transition
2. Détecter les clés d’accès enregistrées : Repérez les utilisateurs qui ont des clés d’accès sur l’ancien domaine
3. Demander une nouvelle inscription : 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 l’adoption faite, mettez l’ancien domaine hors service

// Dans votre Auth0 Action
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 enregistrée
  if (domain === newDomain && hadOldPasskey) {
    const newDomainPasskeys = event.user.app_metadata?.passkey_domains?.includes(newDomain);

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

​

Tests

​

Tester l’enrôlement d’une clé d’accès par domaine

1. Configurer des domaines personnalisés de test : Configurez plusieurs domaines personnalisés dans un tenant de développement
2. Tester l’enrôlement : Enrôlez une clé d’accès à l’aide d’un domaine personnalisé
3. Vérifier l’isolation : Confirmez que la clé d’accès ne fonctionne pas avec les autres domaines personnalisés
4. Tester le réenrôlement : Enrôlez des clés d’accès sur d’autres domaines
5. Tests sur plusieurs navigateurs : Testez dans différents navigateurs et sur différents 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’enrôlement d’une clé d’accès
2. Communication claire : Informez les utilisateurs des exigences d’enrôlement propres à chaque domaine
3. Invitez stratégiquement : Affichez les invites d’enrôlement une fois que les utilisateurs ont démontré leur engagement (p. ex., 3 connexions ou plus)
4. Faites le suivi des inscriptions : Surveillez quels utilisateurs ont inscrit des clés d’accès sur quels domaines
5. Offrez de l’aide : Proposez une documentation claire et du soutien pour la gestion des clés d’accès
6. Testez rigoureusement : 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 changez de domaine personnalisé, prévoyez la réinscription des utilisateurs
8. Surveillez l’adoption : Suivez les taux d’enrôlement 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 configuré une clé d’accès, mais ne peut pas l’utiliser

Causes possibles :

• L’utilisateur se trouve sur un domaine personnalisé différent de celui où il a configuré 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 se trouve sur le bon domaine personnalisé
2. Vérifiez la prise en charge de WebAuthn par le navigateur
3. Au besoin, demandez à l’utilisateur de configurer de nouveau sa clé d’accès

​

L’utilisateur est confus face à plusieurs enrôlements

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’enrôlement se fait par domaine

Résolution :

1. Fournir un message clair indiquant que les clés d’accès sont propres à chaque domaine
2. Indiquer pour quels domaines l’utilisateur a enrôlé des clés d’accès
3. Inviter l’utilisateur à s’enrôler lorsqu’il visite un nouveau domaine

​

En savoir plus

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