Domaine personnalisé par défaut

Apprenez à configurer un domaine personnalisé par défaut pour votre tenant afin d’offrir une expérience utilisateur uniforme.

Lorsque vous avez plusieurs domaines personnalisés configurés pour votre tenant Auth0, vous pouvez en désigner un comme domaine personnalisé par défaut. Le domaine par défaut simplifie la configuration et assure une expérience utilisateur uniforme lorsqu’aucun domaine personnalisé n’est explicitement indiqué.

​

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 :

• Les communications par courriel et par téléphone : l’envoi de courriels de réinitialisation de mot de passe, de liens de vérification du courriel et d’autres notifications générées par Auth0 lorsqu’aucun domaine personnalisé précis n’est indiqué. Cela comprend les cas où des notifications sont envoyées pendant l’authentification.
• Les appels à la Management API : le traitement des requêtes d’API qui déclenchent des notifications sans l’en-tête auth0-custom-domain

Vous pouvez configurer votre domaine canonique de votre tenant (YOUR_TENANT.auth0.com ou YOUR_TENANT.REGION.auth0.com) comme domaine personnalisé par défaut. Il y aura toujours un domaine personnalisé par défaut configuré pour votre tenant.

​

Avantages de définir un domaine par défaut

Définir un domaine personnalisé par défaut offre plusieurs avantages :

• Configuration simplifiée : Réduit la nécessité de préciser des domaines personnalisés dans chaque requête à la Management API ou dans chaque configuration
• Image de marque cohérente : Garantit que les utilisateurs voient toujours votre image de marque, même lorsqu’aucun domaine précis n’est indiqué
• 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 secours : Fournit des valeurs par défaut appropriées pour les mises en œuvre multimarques ou multilocataires
• 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 d’Auth0 Dashboard

Pour définir un domaine personnalisé par défaut dans Auth0 Dashboard :

1. Accédez à Auth0 Dashboard > Branding > Custom Domains
2. Dans la liste, repérez le domaine personnalisé vérifié que vous souhaitez 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 l’étiquette « Default » dans la liste des domaines personnalisés.

Seuls les domaines personnalisés vérifiés peuvent être définis comme domaine 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 au moyen de la Management API, utilisez le point de terminaison PATCH /api/v2/custom-domains/default :

​

Retirer le statut de domaine par défaut

Pour retirer le statut 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 sur le domaine par défaut actuel

Lorsqu’aucun domaine personnalisé n’est défini par défaut, Auth0 utilisera le domaine canonique de votre tenant.

​

Utilisation du domaine par défaut

​

Notifications par courriel

Lorsque Auth0 envoie des notifications par courriel (réinitialisation de 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 sur le domaine personnalisé dans l’adresse « From », 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é spécifiquement 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
• 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 téléphoniques :

• 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 au cas par cas en incluant l’en-tête auth0-custom-domain.

​

Utiliser le domaine par défaut avec Actions

Utilisez Actions pour appliquer 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 renseignements sur le domaine personnalisé dans Actions, consultez Intégration d’Actions avec plusieurs domaines personnalisés.

​

Bonnes pratiques

Lors de la configuration d’un domaine personnalisé par défaut, tenez compte des bonnes pratiques suivantes :

• Choisissez un domaine stable : Sélectionnez un domaine qui ne risque pas de changer souvent comme valeur par défaut
• Vérifiez-le avant de le définir : Assurez-vous que le domaine est entièrement vérifié et fonctionnel avant d’en faire la valeur par défaut
• Documentez la décision : Consignez pourquoi un domaine en particulier a été choisi comme valeur par défaut pour consultation 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
• Surveillez les émetteurs de jetons : Vérifiez que les jetons contiennent la revendication iss attendue après avoir défini une valeur par défaut
• Prévoyez les contextes multimarques : Si vous prenez en charge plusieurs images de marque, choisissez un domaine générique ou administratif comme valeur par défaut
• Mettez à jour les intégrations : Informez votre équipe du domaine par défaut afin d’assurer une configuration adéquate des intégrations

​

En savoir plus

• Domaines personnalisés multiples
• Configurer les fonctionnalités pour utiliser des domaines personnalisés
• Aperçu des domaines personnalisés
• Utiliser des domaines personnalisés dans les courriels
• Intégration d’Actions avec des domaines personnalisés