Migrer vers plusieurs domaines personnalisés

Découvrez comment migrer d’un domaine personnalisé unique vers 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 images de marque, diverses régions ou plusieurs segments de clientèle, ce guide vous propose des instructions étape par étape pour assurer une transition en douceur.

​

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 personnalisés supplémentaires	Vous avez actuellement un domaine personnalisé et souhaitez en ajouter d’autres tout en conservant le domaine existant opérationnel	Expansion pour prendre en charge plusieurs images de marque ou régions	Faible	Aucun
Remplacement d’un domaine existant	Vous souhaitez remplacer votre domaine personnalisé actuel par un nouveau	Changement d’image de marque ou de propriété du domaine	Moyenne	Minime (pendant le basculement DNS)
Migration depuis le domaine canonique	Vous utilisez actuellement votre domaine canonique Auth0 (par exemple, tenant.auth0.com) et souhaitez migrer vers des domaines personnalisés	Mise en œuvre initiale de plusieurs domaines personnalisés	Moyenne à élevée	Aucun (fonctionnement en parallèle)

​

Liste de contrôle pré-migration

Avant de commencer votre migration, assurez-vous d’avoir effectué ce qui suit :

• Vérifié la propriété de tous les nouveaux domaines personnalisés
• Passé en revue les processus d’authentification actuels et les intégrations au niveau de l’API
• Repéré toutes les applications qui utilisent le domaine actuel
• Documenté les modèles de courriel actuels et les liens
• Obtenu les certificats SSL/TLS (si vous utilisez des certificats autogérés)
• Testé la nouvelle configuration de domaine personnalisé dans un environnement de développement ou de préproduction
• Préparé un plan de retour en arrière
• 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 du Auth0 Dashboard ou de la Management API.

​

Vérifier la propriété du domaine

Effectuez le processus de vérification du domaine pour chaque nouveau domaine personnalisé :

​

Pour les certificats gérés par Auth0

1. Prenez note de l’enregistrement CNAME fourni par Auth0
2. Ajoutez l’enregistrement CNAME auprès de 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 gérés par le client

1. Ajoutez l’enregistrement TXT requis à votre configuration 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 souhaitez utiliser un domaine par défaut pour les courriels et les appels d’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 le 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 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 à Branding > Custom Domains
2. Définissez le domaine souhaité comme domaine par défaut
3. Personnalisez vos modèles de courriel pour utiliser les renseignements sur le domaine personnalisé dans l’adresse « From », l’objet et le corps, au besoin

Le fait de définir un 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é sociale (IdP)

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

​

Google

1. Allez à Google Cloud Console
2. Accédez à APIs & Services > Credentials
3. Ajoutez https://new-domain.example.com/login/callback à Authorized redirect URIs

​

Facebook

1. Rendez-vous sur Facebook Developers
2. Accédez à votre application > Facebook Login > Paramètres
3. Ajoutez https://new-domain.example.com/login/callback à URI de redirection OAuth valides

​

Autres fournisseurs

Mettez à jour les URI de redirection de tous les fournisseurs d’identité sociale 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 de l’Assertion Consumer Service (ACS) :

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

Vous n’avez pas à mettre à jour manuellement l’URL ACS dans 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 > App registrations
2. Sélectionnez votre application > Authentication
3. Ajoutez https://new-domain.example.com/login/callback à Redirect URIs

​

Connexions ADFS

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

​

Tester l’authentification

Avant de terminer la migration, testez minutieusement 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 social configuré
5. Appels d’API : vérifiez que les appels d’API fonctionnent avec le nouveau domaine
6. Validation du jeton : assurez-vous que les JWTs contiennent le claim iss correct

​

Surveiller et vérifier

Après la migration :

1. Surveillez les journaux d’authentification pour détecter toute erreur
2. Vérifiez la livraison des courriels et le bon fonctionnement des liens
3. Vérifiez la validité du certificat SSL et les dates 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 (aucun temps d’arrêt)

Faites fonctionner simultanément les anciens et les nouveaux domaines personnalisés :

1. Ajouter le nouveau domaine personnalisé
2. Mettre à jour les nouvelles applications pour utiliser le nouveau domaine
3. Conserver les applications existantes sur l’ancien domaine
4. Migrer progressivement les applications
5. Retirer l’ancien domaine une fois la migration terminée

Avantages : Aucun temps d’arrêt, déploiement progressif, retour en arrière facile

Inconvénients : Surcharge de gestion temporaire

Migration progressive par application

Migrez les applications une à la fois :

1. Identifier les applications selon la priorité ou le risque
2. Migrer d’abord les applications à faible risque
3. Surveiller les problèmes avant de poursuivre
4. Migrer les autres applications
5. Nettoyer les anciennes configurations

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

Inconvénients : Migration plus longue

Déploiement blue-green

Utilisez 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 secours
5. Retirer l’ancien domaine après la période de vérification

Avantages : Tests approfondis, retour en arrière rapide

Inconvénients : Nécessite un environnement distinct

​

Gestion des sessions utilisateur existantes

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

​

Considérations relatives aux sessions

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

​

Approche recommandée

1. Aviser les utilisateurs : Informez les utilisateurs qu’ils pourraient devoir se connecter à nouveau
2. Période de transition : Gardez l’ancien domaine actif pendant la transition
3. Transfert de session : Utilisez Universal Login pour gérer la migration de la session
4. Directives claires : Fournissez des instructions claires si les utilisateurs rencontrent des problèmes

​

Plan de retour en arrière

Si vous rencontrez des problèmes lors de la migration :

​

Retour en arrière immédiat

1. Rétablir les configurations de l’application pour utiliser l’ancien domaine
2. Conserver le nouveau domaine personnalisé configuré pour de futures tentatives
3. Documenter le problème pour le dépannage

​

Retour en arrière partiel

1. Repérez les applications touchées
2. Rétablissez uniquement ces applications sur l’ancien domaine
3. Analysez les problèmes et corrigez-les
4. Relancez la migration lorsque vous serez prêt

​

Retour en arrière complète

1. Mettez à jour toutes les configurations d’application pour utiliser l’ancien domaine
2. Si vous avez défini un domaine par défaut, revenez à l’ancien domaine
3. Informez les utilisateurs de toute action 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) et 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 de courriel 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 d’identité sociale
Émetteur de jeton invalide	La validation du JWT s’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 l’URL du nouveau 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 pendant la migration :

1. Consultez Auth0 Community pour voir si des problèmes semblables ont été signalés
2. Consultez la documentation de dépannage
3. Communiquez avec Auth0 Support en fournissant :
   • Le nom de votre tenant
   • Les ID de domaines personnalisés
   • Une description détaillée du problème
   • Les étapes 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. Documentez la configuration : notez quelles applications utilisent quels domaines personnalisés
2. Surveillez l’expiration des certificats : configurez des alertes pour le renouvellement des certificats
3. Révisez périodiquement : assurez-vous que la configuration des domaines personnalisés correspond aux besoins de l’entreprise
4. Mettez à jour les runbooks : mettez à jour la documentation opérationnelle avec les nouveaux renseignements sur le domaine personnalisé
5. Formez les membres de l’équipe : assurez-vous que votre équipe comprend la nouvelle configuration multidéomaine
6. Prévoyez l’évolution : réfléchissez à la façon dont vous gérerez des domaines supplémentaires à l’avenir

​

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