Migrer vers plusieurs domaines personnalisés

Découvrez comment passer d’un domaine personnalisé unique à plusieurs domaines personnalisés dans Auth0.

Ce guide vous aide à passer d’une configuration avec un seul domaine personnalisé à plusieurs domaines personnalisés. Que vous ajoutiez des domaines pour différentes marques, régions ou segments de clientèle, ce guide fournit des instructions étape par étape pour assurer une transition harmonieuse.

​

Scénarios de migration

Choisissez le scénario qui correspond le mieux à votre situation :

Scénario	Description	Cas d’utilisation	Complexité	Temps d’arrêt
Ajout de domaines supplémentaires	Vous avez actuellement un domaine personnalisé et vous voulez en ajouter d’autres tout en gardant le domaine existant opérationnel	Expansion à plusieurs marques ou régions	Faible	Aucun
Remplacement d’un domaine existant	Vous voulez remplacer votre domaine personnalisé actuel par un nouveau	Changement d’image de marque ou de propriétaire du domaine	Moyenne	Minimal (pendant le basculement DNS)
Migration à partir du domaine canonique	Vous utilisez actuellement votre domaine canonique Auth0 (par ex., tenant.auth0.com) et vous voulez migrer vers des domaines personnalisés	Mise en place initiale de domaines personnalisés avec plusieurs domaines	Moyenne à élevée	Aucun (fonctionnement en parallèle)

​

Liste de vérification préalable à la migration

Avant de commencer la migration, assurez-vous d’avoir effectué les tâches suivantes :

• Vérifié la propriété de tous les nouveaux domaines personnalisés
• Passé en revue les processus d’authentification actuels et les intégrations aux API
• Identifié toutes les applications qui utilisent le domaine actuel
• Documenté les modèles de courriel et les liens actuels
• Obtenu les certificats SSL/TLS (si vous utilisez des certificats autogérés)
• Testé la nouvelle configuration du domaine personnalisé dans un environnement de développement ou de préproduction
• Préparé un plan de repli
• Planifié la migration pendant une période de faible trafic (le cas échéant)
• Informé les parties prenantes et les utilisateurs (au besoin)

​

Étapes de migration

​

Ajoutez vos nouveaux domaines personnalisés

Ajoutez vos nouveaux domaines personnalisés à l’aide de Auth0 Dashboard ou de Management API.

​

Vérifier la propriété du domaine

Terminez le processus de vérification de la propriété du domaine pour chaque nouveau domaine personnalisé :

​

Pour les certificats gérés par Auth0

1. Notez l’enregistrement CNAME fourni par Auth0
2. Ajoutez l’enregistrement CNAME chez votre fournisseur DNS
3. Vérifiez le domaine dans le Dashboard ou au moyen de l’API

# Obtenir les détails de vérification
curl --request GET \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

# Vérifier après l'ajout de l'enregistrement DNS
curl --request POST \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}/verify' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​

Pour les certificats autogérés

1. Ajoutez l’enregistrement TXT requis à votre DNS
2. Configurez votre proxy inverse ou votre CDN
3. Téléversez votre certificat SSL
4. Vérifiez le domaine

​

Configurer le domaine par défaut (facultatif)

Si vous voulez qu’un domaine soit utilisé par défaut pour les courriels et les appels à l’API, définissez-le comme domaine par défaut:

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
  --header 'content-type: application/json' \
  --data '{
    "is_default": true
  }'

​

Mettre à jour la configuration des applications

Mettez à jour vos applications pour utiliser le domaine personnalisé approprié :

​

Configuration du SDK

Mettez à jour l’initialisation de votre SDK Auth0 :

Le seul changement requis consiste à remplacer, dans le paramètre domain, votre domaine canonique Auth0 par votre nouveau domaine personnalisé.

​

URL de rappel

Mettez à jour les URL de rappel de votre application dans Auth0 Dashboard :

1. Accédez à Auth0 Dashboard > Applications. Choisissez l’application à configurer, puis sélectionnez l’onglet Settings.
2. Mettez à jour Allowed Callback URLs pour y inclure le nouveau domaine :
   https://new-domain.example.com/callback
   
3. Mettez à jour Allowed Logout URLs :
   https://new-domain.example.com/logout
   
4. Mettez à jour Allowed Web Origins :
   https://new-domain.example.com
   

​

Mettre à jour les modèles de courriel

Pour rendre les renseignements sur le domaine personnalisé accessibles dans vos modèles de courriel :

1. Accédez à Image de marque > Domaines personnalisés
2. Définissez le domaine voulu comme domaine par défaut
3. Personnalisez vos modèles de courriel pour utiliser, au besoin, les renseignements du domaine personnalisé dans le champ « De », l’objet et le corps du message

Le fait de définir un domaine comme domaine par défaut ne modifie pas automatiquement vos courriels. Cela rend le contexte du domaine par défaut accessible dans les modèles de courriel. Vous devez personnaliser vos modèles pour utiliser cette information. Le contexte du domaine par défaut sera accessible lorsqu’aucun domaine précis n’est fourni au moyen de l’en-tête auth0-custom-domain.

​

Mettre à jour les fournisseurs d’identité sociaux (IdP)

Mettez à jour les URI de redirection de vos fournisseurs d’identité sociaux :

​

Google

1. Accédez à la Google Cloud Console
2. Accédez à APIs et services > Identifiants
3. Ajoutez https://new-domain.example.com/login/callback aux URI de redirection autorisés

​

Facebook

1. Accédez à Facebook Developers
2. Accédez à votre application > Facebook Login > Settings
3. Ajoutez https://new-domain.example.com/login/callback à Valid OAuth Redirect URIs

​

Autres fournisseurs

Mettez à jour les URI de redirection de tous les fournisseurs sociaux configurés en suivant la documentation propre à chacun.

​

Mettre à jour les connexions d’entreprise (le cas échéant)

Si vous utilisez SAML, WS-Fed, Azure AD ou d’autres connexions d’entreprise, mettez à jour leur configuration :

​

Connexions SAML

Mettez à jour l’URL du service de consommation d’assertion (ACS) :

https://new-domain.example.com/login/callback?connection={connectionName}

Vous n’avez pas besoin de mettre à jour manuellement l’URL ACS auprès de votre IdP si vous utilisez des requêtes SAML initiées par le SP et que votre IdP prend en charge l’ACS dynamique.

​

Connexions à Azure AD

1. Accédez à Azure Active Directory > Inscriptions d’applications
2. Sélectionnez votre application > Authentification
3. Ajoutez https://new-domain.example.com/login/callback aux URI de redirection

​

Connexions ADFS

Mettez à jour le point de terminaison dans vos paramètres ADFS pour utiliser le nouveau domaine personnalisé.

​

Tester l’authentification

Avant de terminer la migration, testez soigneusement ce qui suit :

1. Connexion des utilisateurs : Vérifiez que les utilisateurs peuvent s’authentifier à l’aide du nouveau domaine
2. Réinitialisation du mot de passe : Vérifiez que les courriels de réinitialisation du mot de passe utilisent le bon domaine
3. Vérification du courriel : Vérifiez que les liens de vérification du courriel fonctionnent
4. Connexions sociales : Testez chaque fournisseur d’identité sociale configuré
5. Appels d’API : Vérifiez que les appels d’API fonctionnent avec le nouveau domaine
6. Validation des jetons : Assurez-vous que les JWT contiennent la revendication iss appropriée

​

Surveiller et valider

Après la migration :

1. Surveillez les journaux d’authentification pour repérer toute erreur
2. Vérifiez l’envoi des courriels et le bon fonctionnement des liens
3. Vérifiez la validité du certificat SSL et sa date d’expiration
4. Effectuez des tests à partir de différentes régions géographiques (le cas échéant)
5. Confirmez que toutes les applications utilisent les domaines personnalisés prévus

​

Mettre l’ancien domaine hors service (le cas échéant)

Si vous remplacez un domaine personnalisé existant :

1. Assurez-vous que toutes les applications ont été migrées vers le nouveau domaine
2. Surveillez le trafic vers l’ancien domaine pour confirmer qu’il n’est plus utilisé
3. Envisagez de conserver l’ancien domaine actif pendant une période de transition
4. Supprimez l’ancien domaine personnalisé lorsque vous êtes prêt :

curl --request DELETE \
  --url 'https://{yourDomain}/api/v2/custom-domains/{oldCustomDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​

Stratégies de migration

Fonctionnement en parallèle (sans interruption)

Utiliser simultanément l’ancien et le nouveau domaine personnalisé :

1. Ajouter un nouveau domaine personnalisé
2. Mettre à jour les nouvelles applications pour qu’elles utilisent le nouveau domaine
3. Maintenir les applications existantes sur l’ancien domaine
4. Migrer graduellement les applications
5. Mettre l’ancien domaine hors service une fois la migration terminée

Avantages : Aucune interruption, déploiement graduel, retour arrière facile

Inconvénients : Surcharge de gestion temporaire

Migration progressive par application

Migrer les applications une à la fois :

1. Identifier les applications selon leur priorité ou leur niveau de risque
2. Migrer d’abord les applications à faible risque
3. Surveiller l’apparition de problèmes avant de poursuivre
4. Migrer les applications restantes
5. Nettoyer les anciennes configurations

Avantages : Déploiement contrôlé, détection précoce des problèmes

Inconvénients : Échéancier de migration plus long

Déploiement bleu-vert

Utiliser des environnements distincts pour les tests :

1. Configurer le nouveau domaine personnalisé dans l’environnement de préproduction
2. Tester minutieusement toutes les fonctionnalités
3. Basculer la production en une seule opération
4. Conserver l’ancien domaine comme solution de rechange
5. Mettre l’ancien domaine hors service après la période de vérification

Avantages : Tests approfondis, retour arrière rapide

Inconvénients : Nécessite un environnement distinct

​

Gestion des sessions d’utilisateur existantes

Lors de la migration de domaines personnalisés, les sessions d’utilisateur existantes peuvent être affectées :

​

Considérations relatives aux sessions

• Les sessions créées avec l’ancien domaine restent valides jusqu’à leur expiration
• Les nouvelles connexions créeront des sessions avec le nouveau domaine
• Les sessions entre domaines exigent une planification minutieuse

​

Approche recommandée

1. Informer les utilisateurs : Indiquez-leur qu’ils pourraient devoir se reconnecter
2. Période de grâce : Gardez l’ancien Domaine actif pendant la transition
3. Transfert de session : Utilisez Universal Login pour gérer la migration des sessions
4. Consignes claires : Fournissez des instructions claires si les utilisateurs rencontrent des problèmes

​

Plan de retour arrière

Si vous rencontrez des problèmes pendant la migration :

​

Retour arrière immédiat

1. Rétablissez les configurations de l’application pour utiliser l’ancien domaine
2. Conservez le nouveau domaine personnalisé configuré pour de futures tentatives
3. Consignez le problème à des fins de dépannage

​

Retour arrière partiel

1. Identifier les applications touchées
2. Rétablir uniquement ces applications sur l’ancien domaine
3. Enquêter sur les problèmes et les corriger
4. Effectuer de nouveau la migration lorsque vous serez prêt

​

Retour arrière complet

1. Mettez à jour toutes les configurations d’application pour utiliser l’ancien domaine
2. Si vous avez défini un domaine par défaut, remettez l’ancien domaine par défaut
3. Informez les utilisateurs de toute mesure requise
4. Planifiez une nouvelle tentative de migration

​

Dépannage

​

Problèmes courants et solutions

Problème	Cause	Solution
La vérification du domaine échoue	Les enregistrements DNS ne se sont pas encore propagés	Attendez la propagation DNS (cela peut prendre jusqu’à 48 heures), puis vérifiez que l’enregistrement CNAME est correct
La connexion redirige vers l’ancien domaine	La configuration de l’application n’a pas été mise à jour	Mettez à jour l’initialisation du SDK et les URL de rappel
Les liens dans les courriels utilisent le mauvais domaine	Le domaine par défaut n’est pas configuré	Définissez le domaine par défaut ou configurez l’acheminement des courriels
La connexion sociale échoue	Les URI de redirection n’ont pas été mises à jour	Ajoutez le nouveau domaine personnalisé aux URI de redirection autorisées du fournisseur social
Émetteur du jeton non valide	La validation du JWT attend l’ancien domaine	Mettez à jour la validation du jeton pour accepter le nouveau domaine comme émetteur
Erreurs d’assertion SAML	L’URL ACS n’a pas été mise à jour	Mettez à jour la configuration SAML avec la nouvelle URL du domaine personnalisé
Erreurs de certificat	Le certificat n’a pas été provisionné ou a expiré	Vérifiez le domaine, attendez le provisionnement du certificat ou mettez à jour le certificat

​

Obtenir de l’aide

Si vous rencontrez des problèmes durant la migration :

1. Consultez Auth0 Community pour voir si des problèmes similaires ont été signalés
2. Consultez la documentation de dépannage
3. Communiquez avec l’assistance Auth0 en fournissant :
   • Le nom de votre locataire
   • Les ID des domaines personnalisés
   • Une description détaillée du problème
   • Les étapes à suivre pour reproduire le problème
   • Les messages d’erreur ou les journaux

​

Bonnes pratiques après la migration

Après avoir terminé votre migration :

1. Documenter la configuration : consignez les applications qui utilisent chaque domaine personnalisé
2. Surveiller l’expiration des certificats : configurez des alertes pour le renouvellement des certificats
3. Réviser périodiquement : assurez-vous que la configuration des domaines personnalisés répond aux besoins de l’entreprise
4. Mettre à jour les runbooks : mettez à jour la documentation opérationnelle avec les nouvelles informations sur les domaines personnalisés
5. Former les membres de l’équipe : assurez-vous que votre équipe comprend la nouvelle configuration multidomaine
6. Prévoir l’évolutivité : déterminez comment vous gérerez des domaines supplémentaires à l’avenir

​

Pour en savoir plus

• Plusieurs domaines personnalisés
• Domaine personnalisé par défaut
• Management API pour plusieurs domaines personnalisés
• Configurer les fonctionnalités pour utiliser des domaines personnalisés
• Résoudre les problèmes liés aux domaines personnalisés