Cambio de dominio de una aplicación autoalojada: lista de dependencias antes de la migración

Por qué un cambio de dominio es un cambio de aplicación, no solo un cambio de DNS

Para cambiar de forma segura el dominio de una aplicación autoalojada, trate la URL pública como configuración de la aplicación y no como un simple detalle de enrutamiento. El DNS determina dónde resuelve un nombre de host, y un proxy inverso determina qué servicio recibe una solicitud. Ninguno actualiza automáticamente las URL que genera la aplicación, las direcciones de devolución de llamada registradas en servicios externos ni los enlaces que las personas ya utilizan.

El dominio puede aparecer en variables de entorno, configuraciones de administración de la aplicación, registros de base de datos, configuración del proveedor de identidad, suscripciones de webhooks, configuración de clientes de API y plantillas de correo electrónico. También puede estar implícito en los controles de seguridad del navegador: un cambio de host crea un origen web diferente, porque un origen se define por el esquema, el host y el puerto.[1] Por tanto, una integración basada en navegador que funcionaba en el nombre de host anterior puede requerir una actualización explícita de los orígenes permitidos.

Separe el trabajo en dos vías. Los responsables de infraestructura se ocupan de los registros DNS, la validación TLS, el enrutamiento del proxy inverso y las redirecciones del dominio antiguo. Los responsables de la aplicación identifican los ajustes de URL canónica, los servicios conectados, los enlaces orientados al usuario y los flujos de trabajo empresariales. Ambas vías deben estar completas antes de retirar el dominio antiguo.

• No suponga que una consulta DNS correcta demuestra que la migración está completa.
• No suponga que una regla de nombre de host del proxy inverso actualiza la URL base interna de una aplicación.
• No elimine el nombre de host antiguo hasta haber probado las redirecciones, las integraciones y los recorridos de usuario.
• Asigne responsables identificados para la infraestructura, la configuración de la aplicación, las integraciones de identidad y las pruebas de aceptación.

Mapee la URL canónica y todos los nombres de host en uso

Comience con un inventario de nombres de host. El objetivo es encontrar todas las direcciones que la aplicación acepta, publica o de las que depende. Incluya la URL pública canónica actual, la nueva URL canónica prevista, cualquier alternativa con www o sin www, nombres de host administrativos, nombres de host de API, nombres de host de carga o recursos, y subdominios utilizados por servicios integrados.

Para cada nombre de host, registre su propósito, destino DNS actual, destino DNS previsto, requisito de certificado TLS, ruta del proxy inverso, equipo responsable y decisión de retirada. Una ruta o certificado comodín no debe considerarse prueba de que todos los nombres de host funcionen. Por ejemplo, un comodín de un solo nivel como *.example.com no cubre el dominio raíz example.com ni un nombre de varios niveles como api.eu.example.com.[2]

Después determine qué URL considera canónica la aplicación. Es la dirección que utiliza al generar enlaces absolutos, redirecciones, URL de API, URL de recursos o notificaciones. Si la URL canónica sigue siendo old.example.com mientras los usuarios acceden a new.example.com, la interfaz puede parecer funcional hasta que un correo electrónico, un flujo de inicio de sesión o una respuesta de API devuelva a un usuario al dominio antiguo.

• Enumere por separado los nombres de host de producción, preproducción y administración.
• Registre tanto el esquema como el puerto cuando sean pertinentes: http y https no son orígenes intercambiables.
• Busque el nombre de host antiguo en la configuración de la aplicación, archivos de despliegue, almacenes de secretos y documentación.
• Revise marcadores del navegador, enlaces de la wiki interna, documentación pública y enlaces integrados que puedan necesitar un responsable y una fecha de actualización.
• Decida si cada nombre de host antiguo redirigirá, seguirá siendo compatible temporalmente o será retirado.

Encuentre las dependencias que suelen fallar tras un cambio de nombre de host

La configuración de identidad e integraciones suele ser un punto de fallo, porque vincula intencionadamente un cliente o punto de conexión a una dirección precisa. Las URI de redirección de OAuth merecen atención temprana: la guía de seguridad actual de OAuth exige que los servidores de autorización utilicen coincidencia exacta de cadenas para las URI de redirección preregistradas, salvo un caso limitado de localhost para aplicaciones nativas.[3] Por tanto, añadir un dominio nuevo en el proveedor de identidad es una tarea obligatoria antes de la transición, no una comodidad posterior al cambio.

Revise tanto las conexiones entrantes como las salientes. Las dependencias entrantes incluyen devoluciones de llamada del proveedor de identidad, devoluciones de llamada de pagos o formularios, y webhooks de terceros dirigidos a la aplicación. Las dependencias salientes incluyen webhooks enviados por la aplicación a otro servicio, clientes de API que llaman al nombre de host antiguo y widgets o scripts integrados que cargan recursos desde el host anterior.

CORS es otro límite habitual. Si una API o un proxy utiliza una lista explícita de orígenes permitidos, añada el nuevo origen de esquema y host antes de la transición.[4] No amplíe las reglas de origen sin cuidado solo para que una prueba pase; preserve el límite de acceso previsto y aplique el cambio justificado más pequeño.

Las comunicaciones generadas necesitan la misma revisión. Los mensajes de restablecimiento de contraseña, invitaciones, notificaciones de comentarios, exportaciones, informes programados y plantillas de marketing o transaccionales pueden incluir enlaces absolutos. Pruebe con un buzón sin privilegios además de con una cuenta de administrador, ya que las rutas de plantilla y los permisos pueden diferir.

• URL de redirección y cierre de sesión de OAuth y OpenID Connect.
• URL de consumidor de aserciones SAML y referencias de entidad o metadatos, cuando se utilicen.
• Destinos de webhooks y listas de permitidos de remitentes de webhooks.
• URL base de API en scripts, clientes móviles, extensiones de navegador y herramientas internas.
• Listas de orígenes permitidos por CORS, integraciones basadas en navegador y ajustes de iframe.
• Plantillas de correo electrónico, restablecimientos de contraseña, invitaciones, enlaces de calendario y enlaces de notificación.
• URL codificadas de forma fija en flujos de automatización, tareas programadas y documentación.

Compruebe la configuración específica de la aplicación, incluida la configuración que realmente llega al contenedor

Cada aplicación denomina estos ajustes de forma distinta, pero busque conceptos como URL base, URL pública, URL del sitio, URL externa, URL canónica, hosts de confianza, hosts permitidos, orígenes permitidos, modo proxy y confianza en encabezados reenviados. Consulte la documentación del proveedor de la aplicación para conocer los nombres exactos de los ajustes y los requisitos de reinicio. No infiera que un ajuste es opcional porque la aplicación se inicie sin él.

En despliegues basados en Docker, revise la configuración efectiva en tiempo de ejecución en lugar de basarse en un archivo o en un valor recordado. Docker Compose puede proporcionar configuración mediante variables de entorno del contenedor, y los valores de un archivo .env pueden interpolarse en un archivo Compose. La precedencia de las variables de entorno puede modificar el valor que llega a un contenedor.[5] Cuando sea apropiado para su despliegue, docker compose config es una forma útil de confirmar la configuración de Compose resuelta, especialmente si intervienen varios archivos Compose o fuentes de variables.[6]

Inspeccione también los ajustes almacenados fuera de la definición de Compose: paneles de administración de la aplicación, configuración respaldada por bases de datos, archivos de configuración montados, sistemas de gestión de secretos y scripts de inicio. Registre el antes y el después de cada valor modificado. Este registro agiliza mucho la revisión por pares y la reversión.

Si la aplicación se encuentra detrás de un proxy inverso, confirme sus expectativas sobre el host y protocolo originales. Un proxy puede reenviar esta información aguas arriba, pero la confianza en los encabezados reenviados debe configurarse deliberadamente.[7] Una gestión incorrecta puede causar enlaces http generados, bucles de redirección o una discrepancia entre el nombre de host público y el nombre de host que la aplicación cree que sirve.

• La URL canónica o externa coincide con el nombre de host HTTPS planificado.
• La lista de hosts de confianza o permitidos incluye el nuevo nombre de host y, durante la transición, el antiguo si sigue sirviéndose.
• Los ajustes de origen relacionados con CORS y CSRF incluyen únicamente los orígenes necesarios.
• Los ajustes de proxy y protocolo reenviado coinciden con el diseño real del proxy.
• Los ajustes relacionados con OAuth, SSO, webhooks y SMTP se comprueban tanto en la aplicación como en el proveedor externo.
• La configuración resuelta del contenedor se revisa antes del reinicio o redespliegue.
• Hay disponible una copia segura de los ajustes anteriores para la reversión.

Planifique el DNS, TLS y el proxy inverso sin confundirlos con la configuración de la aplicación

Los cambios de infraestructura deben planificarse como una secuencia controlada propia. Cree los nuevos registros DNS, asegúrese de que el proxy inverso tiene una ruta que coincide con el nuevo nombre de host y verifique que se selecciona el servicio de backend correcto. En Traefik, los routers HTTP utilizan reglas de coincidencia de solicitudes, como las reglas Host, para conectar solicitudes a servicios.[2] Las reglas superpuestas requieren especial cuidado: el orden predeterminado puede verse afectado por la longitud de la regla, por lo que una regla amplia puede captar tráfico si las prioridades no se diseñan explícitamente.[2]

Aprovisione y valide TLS antes de declarar listo el nuevo dominio. La emisión de certificados requiere validación de control de dominio. Con el desafío ACME HTTP-01, el token de validación debe ser accesible en el nuevo nombre de host bajo /.well-known/acme-challenge/ en el puerto 80.[8] Compruebe el firewall, el DNS, el enrutamiento del proxy y cualquier comportamiento de redirección que pudiera impedir la validación.

Los clientes de Airbip pueden utilizar un subdominio de Airbip o un dominio personalizado compatible. Airbip gestiona las instancias de aplicación como cargas de trabajo de Docker en servidores cloud de Airbip y automatiza el enrutamiento y los certificados TLS mediante Traefik y Let’s Encrypt, con comprobaciones DNS incluidas en el servicio. Ese soporte de infraestructura no sustituye la revisión por parte del propietario de la aplicación de las URL base, registros de identidad, webhooks, plantillas y flujos de trabajo empresariales.

Utilice una ventana de cambio de DNS que permita la observación, no solo un cambio rápido. Confirme el nuevo nombre de host desde una red externa, inspeccione el certificado y pruebe la ruta prevista. Mantenga disponible la ruta anterior hasta que las comprobaciones de la aplicación y las integraciones aporten evidencia de que es seguro retirarla.

• Cree y verifique el DNS para cada nombre de host nuevo, incluido el nombre raíz cuando sea necesario.
• Confirme que el nuevo nombre de host tiene una ruta de proxy inverso explícita y no ambigua.
• Confirme la emisión de TLS y el nombre del certificado presentado a los clientes.
• Compruebe las redirecciones HTTPS y evite redirigir la ruta de validación ACME fuera de la respuesta de desafío requerida.
• Pruebe el comportamiento entre proxy y aplicación para el host esperado y el protocolo HTTPS.
• Documente la configuración anterior de DNS y proxy antes de realizar cambios irreversibles.

Elija un enfoque de transición: valide en paralelo, redirija deliberadamente y conserve el dominio antiguo durante un período definido

El enfoque de menor riesgo suele consistir en establecer el nuevo nombre de host antes de convertirlo en canónico. Diríjalo a la aplicación, obtenga TLS y complete pruebas controladas mientras el dominio antiguo sigue disponible. Que ambos nombres de host puedan servirse de forma segura al mismo tiempo depende de la validación de hosts de la aplicación, el comportamiento de sesiones, el comportamiento de enlaces generados y las restricciones de licencias o integraciones. Valídelo con la documentación de la aplicación y, cuando sea posible, en un entorno controlado.

Una vez que se acepte el nuevo nombre de host como canónico, redirija las URL públicas antiguas a sus URL nuevas correspondientes cuando sea apropiado conservar las rutas. HTTP 308 es un estado de redirección permanente que utiliza un encabezado Location y conserva el método de la solicitud.[9] Esta propiedad puede ser importante para solicitudes que no sean GET, pero no es una instrucción general para redirigir todos los puntos de conexión. Para API, webhooks, URL firmadas, rutas de carga y clientes automatizados, determine si una redirección es compatible y segura antes de habilitarla.

Establezca un período explícito para el dominio heredado en vez de dejar ambos dominios indefinidamente por accidente. Durante ese período, supervise el acceso al host antiguo, corrija los enlaces codificados de forma fija que queden y notifique a los usuarios o responsables de integración afectados. Conservar un dominio tiene implicaciones operativas y de gobernanza, por lo que la decisión debe ser intencionada y revisada.

• Fase 1: Añada el nuevo dominio, enrútelo, emita TLS y pruébelo sin cambiar los ajustes canónicos de la aplicación cuando el acceso en paralelo sea seguro.
• Fase 2: Actualice la URL canónica y las dependencias de la aplicación, y después pruebe los flujos de trabajo críticos en el nuevo nombre de host.
• Fase 3: Redirija el tráfico de navegador adecuado del dominio antiguo mientras valida por separado el comportamiento de API y webhooks.
• Fase 4: Observe el uso del dominio antiguo, corrija las dependencias restantes y apruebe la retirada según criterios definidos.
• Evite asumir que una redirección preserva solicitudes firmadas, validación de devoluciones de llamada o comportamiento de clientes de terceros.

Ejecute un guion de pruebas posterior al cambio que refleje el trabajo real

Una comprobación de la página de inicio es necesaria, pero insuficiente. Utilice un guion de pruebas escrito con resultados esperados, resultados reales, marcas de tiempo y un responsable de pruebas identificado. Ejecútelo desde una cuenta de usuario normal y una cuenta de administrador, y pruebe desde una sesión de navegador limpia para evitar depender de sesiones o permisos almacenados en caché.

Priorice los flujos de trabajo que crean enlaces externos, atraviesan límites de identidad o escriben datos importantes. Recopile evidencias, como capturas de pantalla de la dirección del navegador, enlaces recibidos por correo electrónico, registros de entrega de webhooks y registros relevantes de aplicación o proxy. La evidencia es más útil que una confirmación verbal al decidir si mantener una redirección o retirar el dominio heredado.

Si falla una prueba, clasifíquela antes de cambiar la configuración: resolución DNS, certificado, ruta de proxy, URL canónica de la aplicación, política de origen del navegador, registro de integración externa o URL codificada de forma fija en el cliente. Esto evita un patrón de respuesta habitual: debilitar controles de seguridad o aplicar redirecciones amplias para ocultar una brecha de propiedad o configuración.

• Abra la nueva URL en una sesión de navegador limpia y confirme HTTPS, el nombre de host esperado y el acceso normal a la aplicación.
• Inicie sesión mediante cada ruta de autenticación local, OAuth, SSO o de administrador compatible.
• Complete los flujos de restablecimiento de contraseña, invitación y verificación de cuenta; inspeccione el nombre de host en los enlaces de correo electrónico recibidos.
• Cree contenido o registros que generen enlaces y abra después esos enlaces en una nueva sesión.
• Pruebe la carga, descarga y vista previa de archivos, así como contenido almacenado externamente o integrado, cuando corresponda.
• Pruebe clientes de API, integraciones de navegador y solicitudes de frontend entre orígenes que utilicen el servicio.
• Active webhooks entrantes y salientes, y confirme el punto de conexión esperado, el tratamiento de firmas y el comportamiento de respuesta.
• Realice flujos de trabajo administrativos clave, incluida la gestión de usuarios y los cambios de configuración adecuados al proceso de modelado de roles de la aplicación. Tenga cuidado de no exponer secretos en evidencias de prueba o registros durante este proceso.

Defina la propiedad, las condiciones de reversión y la evidencia de retirada antes de la ventana de cambio

Una migración de dominio es más fácil de gobernar cuando los puntos de decisión se establecen antes de que cambien registros o ajustes. Designe un responsable técnico del cambio, un responsable de la aplicación, un responsable de identidad e integraciones, un responsable de comunicaciones y una persona que apruebe la retirada del dominio antiguo. En un equipo pequeño, una persona puede asumir varios roles, pero las responsabilidades deben seguir siendo explícitas.

Defina la reversión en términos operativos. Por ejemplo, una reversión puede significar restaurar la URL canónica anterior, volver a habilitar la ruta de proxy previa, restaurar el destino DNS anterior o suspender una redirección mientras se corrige un registro de identidad externo. Identifique qué cambios son rápidamente reversibles y cuáles requieren propagación o acciones de terceros. Mantenga un registro seguro de los valores anteriores y del orden en que deben restaurarse.

Por último, exija evidencia antes de la retirada. La evidencia adecuada incluye pruebas correctas de recorridos críticos en el nuevo nombre de host, devoluciones de llamada OAuth o SSO confirmadas, enlaces de correo electrónico verificados, pruebas de webhooks correctas, ausencia de tráfico no resuelto del dominio antiguo que requiera acción durante el período de observación acordado y aprobación de los responsables de integraciones de alto impacto. La retirada es una decisión empresarial y de gobernanza además de técnica; debe tener en cuenta las comunicaciones con usuarios, los marcadores conservados y cualquier requisito contractual o regulatorio de su organización.

Una plataforma gestionada puede reducir la carga operativa relacionada con el enrutamiento, los certificados, las comprobaciones DNS, la gestión del ciclo de vida del servicio y las copias de seguridad. No puede decidir qué proveedores de identidad, aplicaciones cliente, enlaces o compromisos de gestión de datos son importantes para su organización. Mantenga esa responsabilidad a nivel de aplicación en las personas responsables del servicio.

• Publique un registro de cambio con el nombre de host planificado, la ventana temporal, responsables, dependencias y plan de comunicación con clientes o usuarios.
• Registre de forma segura la configuración anterior de DNS, proxy y aplicación.
• Establezca desencadenantes de reversión medibles, como fallo de inicio de sesión, restablecimiento de contraseña roto, fallo de webhook crítico o enlaces canónicos incorrectos.
• Decida quién puede autorizar la reversión y cómo se informará a los usuarios afectados.
• Establezca criterios de retirada del dominio heredado y un período de observación.
• Archive la evidencia de las pruebas y el inventario final de configuración al finalizar.