Alterar o domínio de uma aplicação autoalojada: lista de verificação de dependências antes da migração

Porque uma alteração de domínio é uma alteração na aplicação, e não apenas no DNS

Para alterar com segurança o domínio de uma aplicação autoalojada, trate o URL público como configuração da aplicação, e não como um simples detalhe de encaminhamento. O DNS determina para onde um nome de anfitrião é resolvido, e um proxy reverso determina qual serviço recebe um pedido. Nenhum deles altera automaticamente os URLs que a aplicação gera, os endereços de callback registados em serviços externos ou as ligações que as pessoas já utilizam.

O domínio pode estar presente em variáveis de ambiente, definições de administração da aplicação, registos da base de dados, configuração do fornecedor de identidade, subscrições de webhooks, configuração de clientes de API e modelos de email. Também pode estar implícito nos controlos de segurança do navegador: uma alteração de anfitrião cria uma origem web diferente, porque uma origem é definida pelo esquema, anfitrião e porta.[1] Por isso, uma integração baseada no navegador que funcionava no nome de anfitrião antigo pode exigir uma atualização explícita das origens permitidas.

Separe o trabalho em duas frentes. Os responsáveis pela infraestrutura tratam dos registos DNS, da validação TLS, do encaminhamento pelo proxy reverso e dos redirecionamentos do domínio antigo. Os responsáveis pela aplicação identificam as definições de URL canónico, os serviços ligados, as ligações visíveis aos utilizadores e os fluxos de trabalho empresariais. Ambas as frentes têm de estar concluídas antes de o domínio antigo ser desativado.

• Não presuma que uma resolução DNS bem-sucedida prova que a migração está concluída.
• Não presuma que uma regra de nome de anfitrião no proxy reverso atualiza o URL base interno da aplicação.
• Não remova o nome de anfitrião antigo até que os redirecionamentos, as integrações e as jornadas dos utilizadores tenham sido testados.
• Atribua responsáveis nomeados para a infraestrutura, a configuração da aplicação, as integrações de identidade e os testes de aceitação.

Mapeie o URL canónico e todos os nomes de anfitrião em utilização

Comece por um inventário de nomes de anfitrião. O objetivo é encontrar todos os endereços que a aplicação aceita, publica ou dos quais depende. Inclua o URL público canónico atual, o novo URL canónico pretendido, qualquer alternativa com www ou sem www, nomes de anfitrião administrativos, nomes de anfitrião de API, nomes de anfitrião de uploads ou recursos e subdomínios utilizados por serviços incorporados.

Para cada nome de anfitrião, registe a respetiva finalidade, o destino DNS atual, o destino DNS pretendido, o requisito de certificado TLS, a rota do proxy reverso, a equipa responsável e a decisão de desativação. Uma rota ou certificado wildcard não deve ser tratado como prova de que todos os nomes de anfitrião funcionam. Por exemplo, um wildcard de nível único como *.example.com não abrange o domínio de raiz example.com nem um nome de vários níveis como api.eu.example.com.[2]

Em seguida, determine qual URL a aplicação considera canónico. Este é o endereço que utiliza ao gerar ligações absolutas, redirecionamentos, URLs de API, URLs de recursos ou notificações. Se o URL canónico continuar a ser old.example.com enquanto os utilizadores acedem a new.example.com, a interface pode parecer funcional até que um email, um fluxo de início de sessão ou uma resposta de API envie um utilizador de volta para o domínio antigo.

• Liste separadamente os nomes de anfitrião de produção, preparação e administração.
• Registe tanto o esquema como a porta quando forem relevantes: http e https não são origens intercambiáveis.
• Pesquise o nome de anfitrião antigo nas definições da aplicação, nos ficheiros de implementação, nos armazenamentos de segredos e na documentação.
• Verifique marcadores do navegador, ligações da wiki interna, documentação pública e ligações incorporadas que possam precisar de um responsável e de uma data de atualização.
• Decida se cada nome de anfitrião antigo será redirecionado, continuará temporariamente suportado ou será desativado.

Encontre dependências que habitualmente falham após uma alteração de nome de anfitrião

As definições de identidade e integração são pontos frequentes de falha porque associam intencionalmente um cliente ou endpoint a um endereço exato. Os URIs de redirecionamento OAuth merecem atenção antecipada: as orientações atuais de segurança OAuth exigem que os servidores de autorização utilizem correspondência exata de cadeia de caracteres para URIs de redirecionamento pré-registados, exceto num caso limitado de localhost para aplicações nativas.[3] Quando o fluxo OAuth utilizado pela aplicação depende de URIs de redirecionamento pré-registados, o novo URI exato tem de ser registado e testado no fornecedor de identidade antes da transição.

Reveja ligações de entrada e de saída. As dependências de entrada incluem callbacks do fornecedor de identidade, callbacks de pagamentos ou formulários e webhooks de terceiros direcionados à aplicação. As dependências de saída incluem webhooks entregues pela aplicação a outro serviço, clientes de API que chamam o nome de anfitrião antigo e widgets ou scripts incorporados que carregam recursos a partir do anfitrião antigo.

O CORS é outro limite comum. Se uma API ou proxy utilizar uma lista explícita de origens permitidas, adicione a nova origem composta por esquema, anfitrião e porta, quando aplicável, antes da transição.[4] Não alargue casualmente as regras de origem apenas para fazer um teste passar; preserve o limite de acesso pretendido e faça a menor alteração justificável.

As comunicações geradas exigem a mesma revisão. Mensagens de reposição de palavra-passe, convites, notificações de comentários, exportações, relatórios agendados e modelos de marketing ou transacionais podem incluir ligações absolutas. Teste com uma caixa de correio sem privilégios, bem como com uma conta de administrador, pois os percursos dos modelos e as permissões podem diferir.

• URLs de redirecionamento e de término de sessão de OAuth e OpenID Connect.
• URLs de consumidor de asserção SAML e referências de entidade ou metadados, quando utilizadas.
• Destinos de webhook e listas de permissões de remetentes de webhook.
• URLs base de API em scripts, clientes móveis, extensões de navegador e ferramentas internas.
• Listas de origens permitidas por CORS, incorporações baseadas no navegador e definições de iframe.
• Modelos de email, reposições de palavra-passe, convites, ligações de calendário e ligações de notificação.
• URLs codificados diretamente em fluxos de automação, tarefas agendadas e documentação.

Verifique a configuração específica da aplicação, incluindo a configuração que realmente chega ao contentor

Cada aplicação dá nomes diferentes a estas definições, mas procure conceitos como URL base, URL público, URL do site, URL externo, URL canónico, anfitriões fidedignos, anfitriões permitidos, origens permitidas, modo de proxy e confiança em cabeçalhos encaminhados. Consulte a documentação do fornecedor da aplicação para saber os nomes exatos das definições e os requisitos de reinício. Não deduza que uma definição é opcional apenas porque a aplicação inicia sem ela.

Para implementações baseadas em Docker, reveja a configuração efetiva em tempo de execução, em vez de confiar num único ficheiro ou num valor de que se recorda. O Docker Compose pode fornecer configuração através de variáveis de ambiente do contentor, e os valores de um ficheiro .env podem ser interpolados num ficheiro Compose. A precedência das variáveis de ambiente pode alterar o valor que chega a um contentor.[5] Quando adequado à sua implementação, docker compose config é uma forma útil de confirmar a configuração Compose resolvida, sobretudo quando estão envolvidos vários ficheiros Compose ou fontes de variáveis.[6]

Inspecione também definições armazenadas fora da definição Compose: painéis de administração da aplicação, configuração guardada na base de dados, ficheiros de configuração montados, sistemas de gestão de segredos e scripts de arranque. Mantenha um registo do antes e do depois para cada valor alterado. Este registo torna a revisão por pares e a reversão muito mais rápidas.

Se a aplicação estiver atrás de um proxy reverso, confirme as suas expectativas relativamente ao anfitrião e protocolo originais. Um proxy pode encaminhar esta informação para montante, mas a confiança nos cabeçalhos encaminhados tem de ser configurada deliberadamente.[7] O tratamento incorreto pode resultar em ligações http geradas, ciclos de redirecionamento ou numa discrepância entre o nome de anfitrião público e aquele que a aplicação acredita servir.

• O URL canónico ou externo corresponde ao nome de anfitrião HTTPS planeado.
• A lista de anfitriões fidedignos ou permitidos inclui o novo nome de anfitrião e, durante a transição, o nome de anfitrião antigo, se este continuar a ser servido.
• As definições de origem relacionadas com CORS e CSRF incluem apenas as origens necessárias.
• As definições de proxy e de protocolo encaminhado correspondem ao desenho real do proxy.
• As definições relacionadas com OAuth, SSO, webhooks e SMTP são verificadas tanto na aplicação como no fornecedor externo.
• A configuração resolvida do contentor é revista antes do reinício ou da nova implementação.
• Está disponível uma cópia segura das definições anteriores para reversão.

Planeie o trabalho de DNS, TLS e proxy reverso sem o confundir com a configuração da aplicação

As alterações de infraestrutura devem ser planeadas como uma sequência controlada própria. Crie os novos registos DNS, assegure que o proxy reverso tem uma rota que corresponde ao novo nome de anfitrião e verifique se foi selecionado o serviço de backend correto. No Traefik, os routers HTTP utilizam regras de correspondência de pedidos, como regras Host, para ligar pedidos a serviços.[2] As regras sobrepostas exigem cuidado adicional: a ordenação predefinida das regras pode ser afetada pelo comprimento da regra, pelo que uma regra abrangente pode captar tráfego se as prioridades não forem concebidas explicitamente.[2]

Providencie e valide TLS antes de declarar o novo domínio pronto. A emissão de certificados exige validação do controlo do domínio. Com o desafio ACME HTTP-01, o token de validação tem de estar acessível no novo nome de anfitrião em /.well-known/acme-challenge/ na porta 80.[8] Verifique a firewall, o DNS, o encaminhamento do proxy e qualquer comportamento de redirecionamento que possa impedir a validação.

Os clientes Airbip podem utilizar um subdomínio Airbip ou um domínio personalizado compatível. A Airbip gere instâncias de aplicações como cargas de trabalho Docker em servidores cloud da Airbip e automatiza o encaminhamento e os certificados TLS através do Traefik e do Let’s Encrypt, com verificações de DNS incluídas no serviço. Este suporte de infraestrutura não substitui a revisão, pelo responsável da aplicação, dos URLs base, registos de identidade, webhooks, modelos e fluxos de trabalho empresariais.

Utilize uma janela de alteração de DNS que permita observação, e não apenas uma troca rápida. Confirme o novo nome de anfitrião a partir de uma rede externa, inspecione o certificado e teste a rota pretendida. Mantenha o caminho antigo disponível até que as verificações da aplicação e das integrações forneçam evidências de que é seguro desativá-lo.

• Crie e verifique o DNS para cada novo nome de anfitrião, incluindo o nome de raiz quando necessário.
• Confirme que o novo nome de anfitrião tem uma rota explícita e inequívoca no proxy reverso.
• Confirme a emissão de TLS e o nome de certificado apresentado aos clientes.
• Verifique os redirecionamentos HTTPS e evite encaminhar o caminho de validação ACME para longe da resposta de desafio necessária.
• Teste o comportamento entre proxy e aplicação para o anfitrião esperado e o protocolo HTTPS.
• Documente a configuração anterior de DNS e proxy antes de efetuar alterações irreversíveis.

Escolha uma abordagem de transição: valide em paralelo, redirecione deliberadamente e mantenha o domínio antigo por um período definido

A abordagem de menor risco é normalmente estabelecer o novo nome de anfitrião antes de o tornar canónico. Encaminhe-o para a aplicação, obtenha TLS e conclua testes controlados enquanto o domínio antigo permanece disponível. A possibilidade de servir ambos os nomes de anfitrião em simultâneo, com segurança, depende da validação de anfitriões, do comportamento das sessões, do comportamento de geração de ligações e das restrições de licenciamento ou integração da aplicação. Valide isto com a documentação da aplicação e, quando possível, num ambiente controlado.

Depois de o novo nome de anfitrião ser aceite como canónico, redirecione os URLs públicos antigos para os URLs novos correspondentes quando for apropriado preservar os caminhos. O HTTP 308 é um estado de redirecionamento permanente que utiliza um cabeçalho Location e preserva o método do pedido.[9] Esta propriedade pode ser importante para pedidos que não sejam GET, mas não é uma instrução geral para redirecionar todos os endpoints. Para APIs, webhooks, URLs assinados, caminhos de uploads e clientes de máquina, determine se um redirecionamento é suportado e seguro antes de o ativar.

Defina um período explícito para o domínio legado, em vez de deixar ambos os domínios ativos indefinidamente por acidente. Durante esse período, monitorize o acesso ao anfitrião antigo, corrija as ligações codificadas diretamente que persistirem e notifique os utilizadores ou responsáveis por integrações afetados. Manter um domínio tem implicações operacionais e de governação, pelo que a decisão deve ser intencional e revista.

• Fase 1: Adicione o novo domínio, encaminhe-o, emita TLS e teste-o sem alterar as definições canónicas da aplicação, quando o acesso paralelo for seguro.
• Fase 2: Atualize o URL canónico e as dependências da aplicação e, em seguida, teste os fluxos de trabalho críticos no novo nome de anfitrião.
• Fase 3: Redirecione o tráfego de navegador adequado do domínio antigo, validando separadamente o comportamento de APIs e webhooks.
• Fase 4: Observe a utilização do domínio antigo, corrija dependências restantes e aprove a desativação com base em critérios definidos.
• Evite assumir que um redirecionamento preserva pedidos assinados, validação de callbacks ou o comportamento de clientes de terceiros.

Execute um roteiro de testes pós-alteração que reflita o trabalho real

Verificar a página inicial é necessário, mas insuficiente. Utilize um roteiro de testes escrito com resultados esperados, resultados reais, carimbos temporais e um testador nomeado. Execute-o a partir de uma conta de utilizador comum e de uma conta de administrador, e teste a partir de uma sessão limpa do navegador para evitar depender de sessões ou permissões em cache.

Dê prioridade aos fluxos de trabalho que criam ligações externas, atravessam limites de identidade ou escrevem dados importantes. Recolha evidências, como capturas de ecrã do endereço no navegador, ligações recebidas por email, registos de entrega de webhook e registos relevantes da aplicação ou do proxy. As evidências são mais úteis do que uma confirmação verbal ao decidir se deve manter um redirecionamento ou desativar o domínio legado.

Se um teste falhar, classifique-o antes de alterar a configuração: resolução DNS, certificado, rota do proxy, URL canónico da aplicação, política de origem do navegador, registo de integração externa ou URL codificado diretamente no cliente. Isto evita um padrão de resposta comum: enfraquecer controlos de segurança ou aplicar redirecionamentos abrangentes para ocultar uma lacuna de responsabilidade ou configuração.

• Abra o novo URL numa sessão limpa do navegador e confirme HTTPS, o nome de anfitrião esperado e o acesso normal à aplicação.
• Inicie sessão por cada caminho de autenticação local, OAuth, SSO ou de administrador suportado.
• Conclua os fluxos de reposição de palavra-passe, convite e verificação de conta; inspecione o nome de anfitrião nas ligações de email recebidas.
• Crie conteúdo ou registos que gerem ligações e, em seguida, abra essas ligações numa nova sessão.
• Teste upload, transferência, pré-visualizações de ficheiros e conteúdo armazenado externamente ou incorporado, quando aplicável.
• Exercite clientes de API, integrações de navegador e pedidos de frontend entre origens que utilizem o serviço.
• Acione webhooks de entrada e de saída e confirme o endpoint esperado, o tratamento de assinaturas e o comportamento da resposta.
• Execute fluxos de trabalho administrativos essenciais, incluindo gestão de utilizadores e alterações de configuração adequadas ao processo de modelação de funções da aplicação. Tenha cuidado para não expor segredos nas evidências de teste ou nos registos durante este processo.

Defina responsáveis, condições de reversão e evidências de desativação antes da janela de alteração

Uma migração de domínio é mais fácil de governar quando os pontos de decisão são definidos antes de qualquer registo ou definição ser alterado. Nomeie um responsável técnico pela alteração, um responsável pela aplicação, um responsável por identidade e integrações, um responsável por comunicações e um aprovador para a desativação do domínio antigo. Numa equipa pequena, uma pessoa pode assumir várias funções, mas as responsabilidades devem continuar explícitas.

Defina a reversão em termos operacionais. Por exemplo, a reversão pode significar restaurar o URL canónico anterior, reativar a rota de proxy anterior, restaurar o destino DNS anterior ou suspender um redirecionamento enquanto um registo de identidade externo é corrigido. Identifique quais alterações são rapidamente reversíveis e quais exigem propagação ou ação de terceiros. Mantenha um registo seguro dos valores anteriores e da ordem pela qual devem ser restaurados.

Por fim, exija evidências antes da desativação. Entre as evidências adequadas estão testes bem-sucedidos de jornadas críticas no novo nome de anfitrião, callbacks OAuth ou SSO confirmados, ligações de email verificadas, testes de webhook bem-sucedidos, ausência de tráfego não resolvido no domínio antigo que exija ação durante o período de observação acordado e aprovação dos responsáveis por integrações de elevado impacto. A desativação é uma decisão empresarial e de governação, bem como técnica; deve ter em conta as comunicações aos utilizadores, os marcadores guardados e quaisquer requisitos contratuais ou regulamentares da sua organização.

Uma plataforma gerida pode reduzir a carga operacional relacionada com encaminhamento, certificados, verificações de DNS, gestão do ciclo de vida dos serviços e cópias de segurança. Não pode decidir quais fornecedores de identidade, aplicações cliente, ligações ou compromissos de tratamento de dados são importantes para a sua organização. Mantenha essa responsabilidade ao nível da aplicação com as pessoas que detêm a gestão do serviço.

• Publique um registo da alteração com o nome de anfitrião planeado, a janela temporal, os responsáveis, as dependências e o plano de comunicação a clientes ou utilizadores.
• Registe de forma segura a configuração anterior de DNS, proxy e aplicação.
• Defina gatilhos de reversão mensuráveis, como falha no início de sessão, reposição de palavra-passe interrompida, falha de webhook crítico ou ligações canónicas incorretas.
• Decida quem pode autorizar a reversão e como os utilizadores afetados serão informados.
• Defina critérios de desativação do domínio legado e um período de observação.
• Arquive as evidências de teste e o inventário final de configuração após a conclusão.