Quando as requisições passam por proxies, balanceadores de carga ou nós CDN antes de chegar ao gateway ASM, o gateway enxerga apenas o endereço IP do último proxy. O cabeçalho X-Forwarded-For (XFF) preserva o IP original do cliente registrando o endereço de cada salto ao longo da cadeia de proxies. Configure o gateway ASM para extrair o IP correto do cliente a partir desse cabeçalho e aprimorar a segurança, otimizar a experiência do usuário ou atender a requisitos de conformidade em cenários de marketing, auditoria e prevenção de fraudes.
O ASM oferece dois métodos de extração: contagem de proxies confiáveis para topologias fixas e exclusão por CIDR confiável para topologias variáveis.
Este recurso exige a versão ASM 1.24.6.83 ou posterior. Caso sua instância execute uma versão anterior, upgrade your ASM instance primeiro.
Como o XFF funciona
Cada proxy no caminho da requisição acrescenta o endereço IP do cliente conectado ao cabeçalho XFF. Quando a requisição chega ao gateway ASM, o cabeçalho contém uma lista separada por vírgulas:
X-Forwarded-For: <client IP>, <proxy 1 IP>, <proxy 2 IP>, ...O endereço mais à esquerda é, geralmente, o IP original do cliente. O gateway precisa distinguir os endereços de clientes dos endereços de proxies para extrair o correto. O ASM oferece duas abordagens:
|
Abordagem |
Quando usar |
Chave de configuração |
|
Contagem de proxies confiáveis |
Todas as requisições passam pelo mesmo número de proxies (topologia fixa) |
|
|
Exclusão por CIDR confiável |
Clientes diferentes passam por números distintos de proxies (topologia variável) |
|
Pré-requisitos
Antes de começar, verifique se você possui:
Uma instância ASM executando a versão 1.24.6.83 ou posterior
kubectl configurado com o kubeconfig do ASM e conectividade com o plano de controle do ASM
Conhecimento da topologia da cadeia de proxies entre seus clientes e o gateway ASM
Configure a contagem de proxies confiáveis (topologia fixa)
Use este método quando todas as requisições passam pelo mesmo número de proxies antes de chegar ao gateway ASM.
Como a contagem funciona
O gateway conta da direita para a esquerda na lista XFF, avançando numTrustedProxies posições, e considera o próximo endereço como o IP do cliente.
Exemplo: Três proxies estão posicionados entre o cliente e o gateway. Defina numTrustedProxies como 2 (total de proxies menos 1).
XFF before gateway processing: [1.1.1.1, 2.2.2.2, 3.3.3.3]
^ client ^ proxy 1 ^ proxy 2
numTrustedProxies: 2 -> skip 2 from the right -> client IP = 1.1.1.1
Passos
-
Abra o recurso de gateway ASM para edite:
kubectl -n istio-system edit istiogateway <gateway-name> -
Adicione a anotação
numTrustedProxiesà especificação do pod do gateway: substitua<proxy-count-minus-1>pelo número total de proxies na cadeia menos 1. Para três proxies, defina este valor como2.AvisoEsta alteração aciona uma reinicialização gradual dos pods do gateway. Aplique-a durante períodos de baixo tráfego.
spec: podAnnotations: proxy.istio.io/config: | gatewayTopology: numTrustedProxies: <proxy-count-minus-1> Salve o arquivo. Os pods do gateway reiniciam automaticamente e aplicam a nova configuração.
Comportamento em casos extremos
|
Cenário |
Entrada XFF |
** |
IP do cliente extraído |
Explicação |
|
Normal (3 proxies) |
|
|
|
Ignora 2 a partir da direita e usa o próximo |
|
Valor igual ao tamanho do XFF |
|
|
|
Retorna ao endereço mais à direita |
|
Valor supera o tamanho do XFF |
|
|
|
Retorna ao endereço mais à direita |
Mantenha numTrustedProxies menor que o número de entradas no cabeçalho XFF. Se o valor for maior ou igual à quantidade de entradas, o gateway usará o endereço mais à direita (último), que é um IP de proxy, e não o IP do cliente.
Comportamento no log de acesso
O gateway acrescenta o IP do proxy downstream ao cabeçalho XFF após extrair o IP do cliente. No exemplo com três proxies, o log de acesso exibe uma entrada adicional (4.4.4.4, o IP do último proxy conectado ao gateway). Essa entrada extra não interfere na extração do IP do cliente.
Configure a exclusão por CIDR confiável (topologia variável)
Use este método quando clientes diferentes chegam ao gateway por caminhos com números distintos de proxies.
Como a exclusão por CIDR funciona
Em vez de contar saltos, o gateway percorre a lista XFF da direita para a esquerda e ignora qualquer endereço que corresponda a um bloco CIDR confiável. O primeiro endereço que não corresponde é tratado como o IP do cliente.
Exemplo: O Client1 se conecta por meio do Proxy1 e do Proxy3, enquanto o Client2 se conecta por meio do Proxy2, Proxy3 e Proxy4. Uma contagem fixa de saltos não consegue lidar com ambos os caminhos. Adicione todos os IPs de proxy à lista de CIDRs confiáveis para que o gateway os ignore e encontre o IP correto do cliente independentemente do comprimento do caminho.
Passos
-
Abra o recurso de gateway ASM para edite:
kubectl -n istio-system edit istiogateway <gateway-name> -
Adicione a anotação
xffTrustedCidrsà especificação do pod do gateway com todos os endereços de proxy conhecidos: substitua os CIDRs de exemplo pelos endereços IP reais ou intervalos CIDR dos proxies posicionados à frente do seu gateway.AvisoEsta alteração aciona uma reinicialização gradual dos pods do gateway. Aplique-a durante períodos de baixo tráfego.
NotaApenas a notação CIDR é suportada. Endereços IP individuais devem usar o sufixo
/32.spec: podAnnotations: proxy.istio.io/config: | gatewayTopology: xffTrustedCidrs: - 2.2.2.2/32 - 3.3.3.3/32 - 4.4.4.4/32 - 5.5.5.5/32 Salve o arquivo. Os pods do gateway reiniciam automaticamente e aplicam a nova configuração.
Referência de parâmetros
|
Parâmetro |
Tipo |
Descrição |
Restrições |
|
|
Inteiro |
Número de saltos de proxies confiáveis a ignorar a partir da extremidade direita da lista XFF. |
Deve ser menor que o número de entradas XFF. Indicado apenas para implantações com topologia fixa. |
|
|
Lista de strings CIDR |
Endereços IP ou intervalos de proxies a excluir ao percorrer a lista XFF da direita para a esquerda. |
Use notação CIDR. IPs individuais exigem o sufixo |
Ambos os parâmetros são defina em gatewayTopology, dentro da anotação de pod proxy.istio.io/config do recurso de gateway ASM (istiogateway).