Migrar a varios dominios personalizados

Aprenda a migrar de un único dominio personalizado a varios dominios personalizados en Auth0.

Esta guía le ayuda a migrar de una configuración con un único dominio personalizado a varios dominios personalizados. Tanto si va a añadir dominios para distintas marcas, regiones o segmentos de clientes, esta guía ofrece instrucciones paso a paso para que la transición sea fluida.

​

Escenarios de migración

Elige el escenario que mejor se ajuste a tu situación:

Escenario	Descripción	Caso de uso	Complejidad	Tiempo de inactividad
Agregar dominios adicionales	Actualmente tienes un dominio personalizado y quieres agregar más sin dejar de mantener operativo el dominio existente	Expandirte para dar servicio a varias marcas o regiones	Baja	Ninguno
Reemplazar un dominio existente	Quieres reemplazar tu dominio personalizado actual por uno nuevo	Cambio de marca o cambio en la propiedad del dominio	Media	Mínimo (durante el cambio de DNS)
Migrar desde el dominio canónico	Actualmente usas tu dominio canónico de Auth0 (por ejemplo, tenant.auth0.com) y quieres migrar a dominios personalizados	Implementación inicial de dominios personalizados con varios dominios	Media a alta	Ninguno (funcionamiento en paralelo)

​

Lista de verificación previa a la migración

Antes de iniciar la migración, asegúrese de haber completado lo siguiente:

• Verificado la propiedad del dominio de todos los nuevos dominios personalizados
• Revisado los procesos de autenticación actuales y las integraciones con API
• Identificado todas las aplicaciones que usan el dominio actual
• Documentado las plantillas actuales de correo electrónico y los enlaces
• Obtenido los certificados SSL/TLS (si usa certificados autogestionados)
• Probado la nueva configuración del dominio personalizado en un entorno de desarrollo o de pruebas
• Preparado un plan de reversión
• Programado la migración durante un período de poco tráfico (si corresponde)
• Notificado a las partes interesadas y a los usuarios (si es necesario)

​

Pasos para la migración

​

Agrega tus nuevos dominios personalizados

Agrega tus nuevos dominios personalizados mediante Auth0 Dashboard o la Management API.

​

Verifica la propiedad del dominio

Completa el proceso de verificación del dominio para cada nuevo dominio personalizado:

​

Para certificados gestionados por Auth0

1. Anote el registro CNAME proporcionado por Auth0
2. Añada el registro CNAME a su proveedor de DNS
3. Verifique el dominio desde el Dashboard o la API

# Obtener detalles de verificación
curl --request GET \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

# Verificar después de agregar el registro DNS
curl --request POST \
  --url 'https://{yourDomain}/api/v2/custom-domains/{customDomainId}/verify' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

​

Para certificados autogestionados

1. Agregue el registro TXT requerido en su DNS
2. Configure su proxy inverso o CDN
3. Cargue su certificado SSL
4. Verifique el dominio

​

Configurar el dominio predeterminado (opcional)

Si quiere que se use un dominio de forma predeterminada para los correos electrónicos y las llamadas a la API, configúrelo como dominio predeterminado:

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

​

Actualiza la configuración de las aplicaciones

Actualiza tus aplicaciones para que usen el dominio personalizado adecuado:

​

Configuración del SDK

Actualiza la inicialización del SDK de Auth0:

El único cambio necesario es actualizar el parámetro domain para que use tu nuevo dominio personalizado en lugar del dominio canónico de Auth0.

​

URL de callback

Actualiza las URL de callback de tu aplicación en Auth0 Dashboard:

1. Ve a Auth0 Dashboard > Applications. Elige la aplicación que quieres configurar y selecciona la pestaña Settings.
2. Actualiza Allowed Callback URLs para incluir el nuevo dominio:
   https://new-domain.example.com/callback
   
3. Actualiza Allowed Logout URLs:
   https://new-domain.example.com/logout
   
4. Actualiza Allowed Web Origins:
   https://new-domain.example.com
   

​

Actualizar las plantillas de correo electrónico

Para que la información del dominio personalizado esté disponible en tus plantillas de correo electrónico:

1. Ve a Marca > Dominios personalizados
2. Establece como predeterminado el dominio que prefieras
3. Personaliza tus plantillas de correo electrónico para usar la información del dominio personalizado en la dirección «From», el asunto y el cuerpo, según sea necesario

Establecer un dominio como predeterminado no cambia automáticamente tus correos electrónicos. Hace que el contexto del dominio predeterminado esté disponible en las plantillas de correo electrónico. Debes personalizar tus plantillas para usar esa información. El contexto del dominio predeterminado estará disponible cuando no se proporcione un dominio específico mediante el encabezado auth0-custom-domain.

​

Actualice los proveedores de identidad social (IdP)

Actualice los URI de redirección de sus proveedores de identidad social:

​

Google

1. Ve a Google Cloud Console
2. Ve a APIs & Services > Credentials
3. Agrega https://new-domain.example.com/login/callback a URI de redirección autorizados

​

Facebook

1. Ve a Facebook Developers
2. Ve a tu aplicación > Facebook Login > Configuración
3. Agrega https://new-domain.example.com/login/callback a URI de redirección OAuth válidos

​

Otros proveedores

Actualiza los URI de redirección de todos los proveedores sociales configurados siguiendo la documentación de cada proveedor.

​

Actualizar conexiones empresariales (si corresponde)

Si usa SAML, WS-Fed, Azure AD u otras conexiones empresariales, actualice la configuración correspondiente:

​

Conexiones SAML

Actualice la URL del Servicio de Consumo de Aserciones (ACS):

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

No necesita actualizar manualmente la URL de ACS en su IdP si usa solicitudes SAML iniciadas por el SP y su IdP acepta ACS dinámico.

​

Conexiones de Azure AD

1. Vaya a Azure Active Directory > Registros de aplicaciones
2. Seleccione su aplicación > Autenticación
3. Agregue https://new-domain.example.com/login/callback a URI de redirección

​

Conexiones de ADFS

Actualiza el endpoint en la configuración de ADFS para que use el nuevo dominio personalizado.

​

Pruebe la autenticación

Antes de completar la migración, pruebe exhaustivamente lo siguiente:

1. Inicio de sesión de usuarios: Verifique que los usuarios puedan autenticarse a través del nuevo dominio
2. Restablecimiento de contraseña: Compruebe que los correos electrónicos de restablecimiento de contraseña utilicen el dominio correcto
3. Verificación de correo electrónico: Verifique que los enlaces de verificación de correo electrónico funcionen
4. Inicios de sesión sociales: Pruebe cada proveedor social configurado
5. Llamadas a la API: Verifique que las llamadas a la API funcionen con el nuevo dominio
6. Validación de tokens: Asegúrese de que los JWT incluyan el claim iss correcto

​

Supervisión y verificación

Después de la migración:

1. Supervise los registros de autenticación para detectar cualquier error
2. Compruebe la entrega de correos electrónicos y el funcionamiento de los enlaces
3. Verifique la validez del certificado SSL y las fechas de vencimiento
4. Haga pruebas desde distintas regiones geográficas (si corresponde)
5. Confirme que todas las aplicaciones estén usando los dominios personalizados previstos

​

Retirar el dominio antiguo (si aplica)

Si vas a reemplazar un dominio personalizado existente:

1. Asegúrate de que todas las aplicaciones se hayan migrado al nuevo dominio
2. Supervisa el tráfico al dominio antiguo para confirmar que ya no está en uso
3. Considera mantener activo el dominio antiguo durante un período de gracia
4. Elimina el dominio personalizado antiguo cuando estés listo:

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

​

Patrones de migración

Operación en paralelo (sin tiempo de inactividad)

Ejecute simultáneamente los dominios personalizados antiguo y nuevo:

1. Agregue un nuevo dominio personalizado
2. Actualice las aplicaciones nuevas para que usen el nuevo dominio
3. Mantenga las aplicaciones existentes en el dominio antiguo
4. Migre las aplicaciones gradualmente
5. Retire el dominio antiguo cuando la migración se haya completado por completo

Ventajas: Sin tiempo de inactividad, despliegue gradual, reversión sencilla

Desventajas: Sobrecarga administrativa temporal

Migración por fases por aplicación

Migre las aplicaciones una por una:

1. Identifique las aplicaciones por prioridad o riesgo
2. Migre primero las aplicaciones de bajo riesgo
3. Supervise si hay problemas antes de continuar
4. Migre las aplicaciones restantes
5. Limpie las configuraciones antiguas

Ventajas: Despliegue controlado, detección temprana de problemas

Desventajas: Cronograma de migración más largo

Implementación blue-green

Use entornos separados para las pruebas:

1. Configure el nuevo dominio personalizado en el entorno de ensayo
2. Pruebe exhaustivamente toda la funcionalidad
3. Cambie a producción en una sola operación
4. Mantenga el dominio antiguo como respaldo
5. Retire el dominio antiguo después del período de verificación

Ventajas: Pruebas exhaustivas, reversión rápida

Desventajas: Requiere un entorno separado

​

Gestión de las sesiones de usuario existentes

Al migrar los dominios personalizados, las sesiones de usuario existentes pueden verse afectadas:

​

Consideraciones sobre las sesiones

• Las sesiones creadas con el dominio anterior seguirán siendo válidas hasta que caduquen
• Los nuevos inicios de sesión crearán sesiones con el nuevo dominio
• Las sesiones entre dominios requieren una planificación minuciosa

​

Enfoque recomendado

1. Notifique a los usuarios: Infórmeles de que es posible que tengan que volver a iniciar sesión
2. Período de gracia: Mantenga el dominio anterior activo durante la transición
3. Transferencia de sesión: Use Universal Login para gestionar la migración de sesiones
4. Instrucciones claras: Proporcione instrucciones claras si los usuarios tienen problemas

​

Plan de reversión

Si encuentras problemas durante la migración:

​

Reversión inmediata

1. Revierte la configuración de la aplicación para usar el dominio anterior
2. Mantén configurado el nuevo dominio personalizado para intentos futuros
3. Documenta el problema para su solución

​

Reversión parcial

1. Identifique las aplicaciones afectadas
2. Revierta únicamente esas aplicaciones al dominio anterior
3. Investigue y corrija los problemas
4. Vuelva a migrarlas cuando esté listo

​

Reversión completa

1. Actualice toda la configuración de la aplicación para usar el dominio anterior
2. Si configuró un dominio predeterminado, cámbielo de nuevo al dominio anterior
3. Notifique a los usuarios cualquier acción requerida
4. Programe otro intento de migración

​

Solución de problemas

​

Problemas comunes y soluciones

Problema	Causa	Solución
La verificación del dominio falla	Los registros DNS aún no se han propagado	Espere a que se propaguen los registros DNS (puede tardar hasta 48 horas) y verifique que el registro CNAME sea correcto
El inicio de sesión redirige al dominio anterior	La configuración de la aplicación no se ha actualizado	Actualice la inicialización del SDK y las URL de callback
Los enlaces de correo electrónico usan el dominio incorrecto	El dominio predeterminado no está configurado	Configure el dominio predeterminado o el enrutamiento del correo electrónico
El inicio de sesión con redes sociales falla	Las URI de redirección no se han actualizado	Agregue el nuevo dominio personalizado a las URI de redirección permitidas del proveedor social
Emisor del token no válido	La validación del JWT espera el dominio anterior	Actualice la validación del token para aceptar el nuevo dominio como emisor
Errores de aserción SAML	La URL de ACS no se ha actualizado	Actualice la configuración de SAML con la nueva URL del dominio personalizado
Errores de certificado	El certificado no se ha aprovisionado o ha caducado	Verifique el dominio, espere a que se aprovisione el certificado o actualice el certificado

​

Obtener ayuda

Si encuentra problemas durante la migración:

1. Consulte Auth0 Community para ver si hay problemas similares
2. Revise la documentación de solución de problemas
3. Póngase en contacto con Auth0 Support e incluya:
   • El nombre de su inquilino
   • Los ID de los dominios personalizados
   • Una descripción detallada del problema
   • Los pasos para reproducirlo
   • Mensajes de error o registros

​

Prácticas recomendadas después de la migración

Después de completar la migración:

1. Documente la configuración: Registre qué aplicaciones usan qué dominios personalizados
2. Supervise el vencimiento de los certificados: Configure alertas para la renovación de certificados
3. Revise periódicamente: Asegúrese de que la configuración de los dominios personalizados se ajuste a las necesidades del negocio
4. Actualice los runbooks: Actualice la documentación operativa con la nueva información sobre dominios personalizados
5. Capacite a los miembros del equipo: Asegúrese de que su equipo comprenda la nueva configuración multidominio
6. Planifique la escalabilidad: Considere cómo administrará dominios adicionales en el futuro

​

Más información

• Múltiples dominios personalizados
• Dominio personalizado predeterminado
• Management API para múltiples dominios personalizados
• Configurar funciones para usar dominios personalizados
• Solucionar problemas con dominios personalizados