Passer au contenu principal
Lorsque plusieurs domaines personnalisés sont configurés pour votre locataire Auth0, vous pouvez en définir un comme domaine personnalisé par défaut. Le domaine par défaut simplifie la configuration et assure une expérience utilisateur cohérente lorsqu’aucun domaine personnalisé n’est explicitement précisé.

​
Qu’est-ce qu’un domaine personnalisé par défaut?

Le domaine personnalisé par défaut est le domaine personnalisé qu’Auth0 utilise automatiquement pour :
  • Communications par courriel et par téléphone : l’envoi des courriels de réinitialisation de mot de passe, des liens de vérification du courriel et d’autres notifications générées par Auth0 lorsqu’aucun domaine personnalisé précis n’est spécifié. Cela inclut les cas où des notifications sont envoyées pendant l’authentification.
  • Appels à la Management API : le traitement des requêtes API qui déclenchent des notifications sans l’en-tête auth0-custom-domain
Vous pouvez configurer le domaine canonique de votre locataire (YOUR_TENANT.auth0.com ou YOUR_TENANT.REGION.auth0.com) comme domaine personnalisé par défaut. Un domaine personnalisé par défaut sera toujours configuré pour votre locataire.

​
Avantages de définir un domaine par défaut

Définir un domaine personnalisé par défaut présente plusieurs avantages :
  • Configuration simplifiée : Réduit le besoin de préciser des domaines personnalisés dans chaque appel à la Management API ou dans la configuration
  • Image de marque cohérente : Garantit que les utilisateurs voient toujours votre marque, même lorsqu’aucun domaine précis n’est spécifié
  • En-tête auth0-custom-domain facultatif : Rend l’en-tête de domaine personnalisé facultatif dans les requêtes à la Management API
  • Comportement de rechange : Fournit des valeurs par défaut pertinentes pour les implémentations multimarques ou à plusieurs locataires
  • Migration facilitée : Simplifie le passage d’un seul domaine personnalisé à plusieurs domaines personnalisés

​
Configurer un domaine par défaut

Vous pouvez définir un domaine personnalisé par défaut à partir de l’Auth0 Dashboard ou de la Management API.

​
Utilisation du Auth0 Dashboard

Pour définir un domaine personnalisé par défaut dans le Auth0 Dashboard :
  1. Accédez à Auth0 Dashboard > Branding > Custom Domains
  2. Dans la liste, repérez le domaine personnalisé vérifié que vous voulez définir par défaut
  3. Cliquez sur le bouton Set as Default pour ce domaine
  4. Confirmez l’action dans la boîte de dialogue qui s’affiche
Le domaine affichera maintenant le badge « Default » dans la liste des domaines personnalisés.
Seuls les domaines personnalisés vérifiés peuvent être définis par défaut. Assurez-vous que votre domaine personnalisé est entièrement vérifié et actif avant de le désigner comme domaine par défaut.

​
Utiliser la Management API

Pour définir un domaine personnalisé par défaut à l’aide de la Management API, utilisez le point de terminaison PATCH /api/v2/custom-domains/default :

​
Supprimer la désignation par défaut d’un domaine

Pour supprimer la désignation par défaut d’un domaine personnalisé :
  1. Définissez un autre domaine personnalisé comme domaine par défaut (un seul domaine peut être défini par défaut à la fois), ou
  2. Utilisez la Management API pour définir is_default: false pour le domaine actuellement défini par défaut
Lorsqu’aucun domaine personnalisé n’est défini par défaut, Auth0 utilisera le domaine canonique de votre locataire.

​
Utilisation du domaine par défaut

​
Notifications par courriel

Lorsque Auth0 envoie des notifications par courriel (réinitialisation du mot de passe, vérification du courriel, courriels de bienvenue), le domaine par défaut est utilisé pour les liens et la personnalisation de ces notifications. Vous pouvez personnaliser les modèles de courriel pour utiliser les renseignements du domaine personnalisé dans l’adresse « De », l’objet et le corps du courriel.

​
Points de terminaison de la Management API qui déclenchent des notifications

Le domaine personnalisé par défaut est utilisé précisément pour les points de terminaison de la Management API qui déclenchent des notifications par courriel ou par téléphone. L’en-tête auth0-custom-domain devient facultatif pour ces points de terminaison lorsqu’un domaine par défaut est configuré. Points de terminaison qui déclenchent des notifications par courriel :
  • POST /api/v2/tickets/password-change - Envoie un courriel de réinitialisation du mot de passe
  • POST /api/v2/tickets/email-verification - Envoie un courriel de vérification de l’adresse courriel
  • POST /api/v2/jobs/verification-email - Envoie un courriel de vérification à un ou plusieurs utilisateurs
  • POST /api/v2/users - Peut déclencher un courriel de bienvenue si cette option est configurée
  • PATCH /api/v2/users/{id} - Peut déclencher un courriel de vérification lorsque l’adresse courriel est mise à jour
Points de terminaison qui déclenchent des notifications par téléphone :
  • POST /api/v2/users/{id}/phone/verification - Envoie un code de vérification par SMS
Exemple : Si vous ne fournissez pas l’en-tête auth0-custom-domain pour ces points de terminaison de notification, Auth0 utilise automatiquement le domaine personnalisé par défaut pour les liens et les personnalisations dans le courriel ou le SMS. Vous pouvez remplacer ce comportement pour chaque requête en incluant l’en-tête auth0-custom-domain.

​
Utiliser le domaine par défaut avec Actions

Utilisez Actions pour mettre en œuvre une logique basée sur le domaine personnalisé : 
exports.onExecutePostLogin = async (event, api) => {
  const domain = event.custom_domain?.domain;

  // Stocker le domaine de connexion dans les métadonnées de l'utilisateur
  if (domain) {
    api.user.setAppMetadata('login_domain', domain);
  }
};
Pour en savoir plus sur l’utilisation des informations relatives aux domaines personnalisés dans Actions, consultez Intégration d’Actions à plusieurs domaines personnalisés.

​
Bonnes pratiques

Lorsque vous configurez un domaine personnalisé par défaut, tenez compte des bonnes pratiques suivantes :
  • Choisissez un domaine stable : Sélectionnez un domaine qui ne changera pas souvent comme domaine par défaut
  • Vérifiez-le avant de le définir : Assurez-vous que le domaine est entièrement vérifié et opérationnel avant d’en faire le domaine par défaut
  • Documentez la décision : Consignez pourquoi un domaine précis a été choisi comme domaine par défaut pour référence ultérieure
  • Testez les flux de courriel : Après avoir défini un domaine par défaut, testez les flux de réinitialisation du mot de passe et de vérification du courriel
  • Vérifiez les émetteurs des jetons : Assurez-vous que les jetons contiennent la revendication iss attendue après avoir défini le domaine par défaut
  • Prévoyez les scénarios à plusieurs marques : Si vous prenez en charge plusieurs marques, choisissez un domaine générique ou d’administration comme domaine par défaut
  • Mettez à jour les intégrations : Informez votre équipe du domaine par défaut pour assurer une configuration adéquate des intégrations

​
En savoir plus