Cabeçalhos encaminhados e relacionados ao host enviados para backends HTTP não correspondem às expectativas do backend

Descubra como diagnosticar e solucionar problemas de cabeçalhos encaminhados e relacionados ao host enviados para backends HTTP ao chamar APIs, tendo criado com sucesso gateways de API e implantações de API com o serviço API Gateway.

Use este tópico para diagnosticar e solucionar problemas de cabeçalhos encaminhados e relacionados ao host que um back-end HTTP recebe por meio do Gateway de API. Os valores de cabeçalho podem afetar redirecionamentos, geração de URL, lógica de controle de acesso e roteamento de aplicativo.

O API Gateway adiciona alguns cabeçalhos de encaminhamento, preserva alguns valores fornecidos pelo cliente, anexa valores a algumas cadeias de cabeçalhos e reescreve o cabeçalho Host para o destino de back-end. Verifique os cabeçalhos que o back-end recebe antes de alterar a lógica do aplicativo ou a configuração de implantação.

Sintomas do Problema

Você pode ver um ou mais dos seguintes sintomas:

O serviço de back-end espera Forwarded: host=<client-hostname>, mas o valor está ausente.
O serviço de back-end recebe apenas entradas Forwarded: for=....
O serviço de back-end recebe o nome do host de destino do back-end no cabeçalho Host em vez do nome do host voltado para o cliente.
Redirecionamentos, URLs gerados ou lógica de controle de acesso baseada em host funcionam de maneira diferente depois que a API é colocada atrás do Gateway de API.
O serviço de back-end recebe vários valores Forwarded ou X-Forwarded-For, e o aplicativo trata apenas um valor.

Possíveis Causas

Incompatibilidades de cabeçalho encaminhadas e de host podem ocorrer pelos seguintes motivos:

O aplicativo espera Forwarded: host=... ou Forwarded: proto=..., mas o Gateway de API adiciona apenas uma entrada for=... por padrão.
O aplicativo lê o cabeçalho Host, mas o Serviço API Gateway regravará esse cabeçalho para o destino de back-end.
O aplicativo espera um único valor de encaminhamento, mas a solicitação contém uma cadeia de encaminhamento.
A implantação não inclui uma transformação de cabeçalho de solicitação que passa o host voltado para o cliente para o back-end.

Compreender o comportamento do cabeçalho encaminhado

Para back-ends de HTTP, o API Gateway adiciona cabeçalhos de solicitação que contêm informações de IP do cliente.

A solicitação para o back-end pode incluir os seguintes cabeçalhos:

X-Real-IP
Forwarded
X-Forwarded-For
User-Agent: Oracle API Gateway

O valor Forwarded padrão é uma entrada for=.... O Serviço API Gateway não adiciona automaticamente valores host=... ou proto=... ao cabeçalho Forwarded.

Se o cliente enviar cabeçalhos de encaminhamento existentes, o API Gateway preservará esses valores e anexará suas próprias informações de IP do cliente. Portanto, o back-end pode receber uma cadeia de valores Forwarded ou X-Forwarded-For.

Compreender o comportamento do cabeçalho do host

Para back-ends de HTTP, o cabeçalho Host na solicitação para o back-end não é o host voltado para o cliente original por padrão. O Serviço API Gateway regravará o cabeçalho Host para o destino de back-end.

Se o aplicativo precisar do host voltado para o cliente, configure uma transformação de cabeçalho de solicitação que copie o valor Host de entrada em um cabeçalho lido pelo aplicativo. Por exemplo, use a variável de contexto request.host para copiar o host de entrada para X-Forwarded-Host ou para um cabeçalho específico do aplicativo.

Não confie no cabeçalho Host da solicitação de back-end para preservar o nome do host externo.

Revisar cabeçalhos recebidos

Repita a solicitação por meio do API Gateway e inspecione os cabeçalhos que o back-end recebe.

Revise os seguintes valores de cabeçalho:

O cabeçalho Forwarded visível do back-end.
O cabeçalho X-Forwarded-For visível do back-end.
O cabeçalho Host visível do back-end.
O cabeçalho X-Forwarded-Host visível do back-end, se a rota usar esse cabeçalho.
Qualquer cabeçalho personalizado que a implantação cria com base no valor Host de entrada.

Se possível, use um ponto final temporário que ecoe cabeçalhos de solicitação. A resposta ecoada mostra os valores do cabeçalho que chegaram ao back-end.

Revisar a Configuração da Implantação

Revise a configuração de implantação de API no Gateway de API para identificar a rota correspondente e quaisquer transformações de cabeçalho de solicitação nessa rota.

Confirme os seguintes valores de configuração:

O valor backend.url da rota.
O valor routes.path que correspondeu à solicitação.
As transformações do cabeçalho da solicitação na rota correspondente.

Se o back-end depender do nome do host voltado para o cliente, confirme se a rota copia o valor Host de entrada em um cabeçalho que o back-end pode ler.

Se o back-end depender de Forwarded: host=..., confirme se sua própria estratégia de cabeçalho define esse valor. Não suponha que o Gateway de API crie o valor automaticamente.

Corrigir Problemas de Cabeçalho de Host e Encaminhados

Aplique a correção que corresponde ao valor do cabeçalho que o back-end exige:

Se o back-end puder usar X-Forwarded-Host, configure a rota para enviar esse cabeçalho e atualize o aplicativo para lê-lo.
Se o back-end precisar do host voltado para o cliente em um cabeçalho personalizado, crie uma transformação de cabeçalho de solicitação com base no valor Host de entrada.
Se o back-end esperar Forwarded: host=..., atualize o aplicativo para usar os cabeçalhos que o Gateway de API fornece ou adicione uma estratégia de cabeçalho explícita que o aplicativo pode consumir.
Se o back-end analisar apenas um valor Forwarded ou X-Forwarded-For, atualize o aplicativo para tratar uma cadeia de encaminhamento.

Verificar Cabeçalhos de Host e Encaminhados

Depois de atualizar a implantação ou a lógica do aplicativo, repita a solicitação e verifique o resultado.

Confirme os seguintes resultados:

O back-end recebe o valor de host voltado para o cliente esperado no cabeçalho configurado.
O back-end trata vários valores Forwarded ou X-Forwarded-For corretamente.
Redirecionamentos, URLs gerados e lógica baseada em host usam o nome de host e o esquema esperados.
A lógica de controle de acesso baseada em host retorna a resposta esperada.

Para obter mais informações

Para obter mais informações, consulte:

Documentação do Oracle Cloud Infrastructure