Web Application Firewall:Retrieve real client IP from an HTTP header

Como funciona

Após conectar o domínio ao WAF usando acesso CNAME, as requisições dos clientes passam primeiro pelo WAF e, possivelmente, por outros proxies intermediários (como CDN ou Anti-DDoS Pro) antes de chegar ao servidor de origem. Nesse ponto, o endereço IP de origem da conexão TCP recebida pelo servidor de origem é o endereço IP do proxy do último salto, e não o endereço IP real do cliente.

Quando o WAF encaminha requisições HTTP, ele adiciona automaticamente o campo de cabeçalho X-Forwarded-For. O valor inicial desse campo é o endereço IP do cliente. Cada vez que a requisição passa por um nó de proxy, o endereço IP desse nó é anexado ao final do campo no seguinte formato:

X-Forwarded-For: client IP, proxy 1 IP, proxy 2 IP, …

Portanto, configure o servidor web de backend para extrair o endereço IP mais à esquerda do cabeçalho X-Forwarded-For, pois este corresponde ao endereço IP original do cliente. As seções a seguir descrevem os métodos de configuração para diferentes plataformas.

Etapa 1: Obter os intervalos de IP de back-to-origin do WAF

Faça login no console do Web Application Firewall. Na barra de navegação superior, selecione o grupo de recursos e a região da sua instância do WAF (Chinese Mainland ou Outside Chinese Mainland). Em seguida, clique em Onboarding > CNAME Record > View Back-to-origin CIDR Blocks e anote todos os intervalos de IP de back-to-origin do WAF para uso na configuração posterior.

Configurar o Nginx

O Nginx utiliza o módulo http_realip_module para analisar o X-Forwarded-For. Siga as etapas abaixo para modificar a configuração do Nginx.

nginx -V 2>&1 | grep -o with-http_realip_module

# For Alibaba Cloud Linux / CentOS / RHEL
sudo yum reinstall nginx -y
# For Ubuntu / Debian
sudo apt install --reinstall nginx-core nginx-full

Configurar o IIS 7 (aplicável ao IIS 7 e versões posteriores)

Quando o WAF atua como proxy reverso, o campo c-ip nos logs padrão do IIS registra o IP de back-to-origin do WAF em vez do IP real do cliente. Utilize o recurso de campos de log personalizados W3C no IIS para gravar o cabeçalho de requisição X-Forwarded-For nos logs, facilitando auditorias e solução de problemas.

1. Abra o Gerenciador do IIS. Na árvore de Conexões à esquerda, expanda o nó do servidor e selecione o site desejado (por exemplo, Default Web Site).

2. No painel Features View à direita, dê um clique duplo no ícone Logging.

3. Na seção Log Files, confirme se o Format está definido como W3C (valor padrão). Caso outro formato esteja selecionado, altere-o para W3C.

4. Ainda na seção Log Files, clique em Select Fields....

5. Na parte inferior da caixa de diálogo exibida, clique em Add Field....

6. Na caixa de diálogo Add Custom Field, insira as informações abaixo e clique em OK.

   Parâmetro	Descrição
   Field Name	Insira X-FORWARDED-FOR
   Source Type	Selecione Request Header
   source	Insira X-Forwarded-For

7. Clique em OK para salvar o campo personalizado.

8. Clique em OK novamente para fechar a janela de campos de log e, em seguida, clique em Apply no painel Ações para salvar as alterações.

9. Reinicie o IIS para que as alterações entrem em vigor.

10. Acesse o site para validar a configuração e visualize os logs de acesso (caminho padrão: C:\inetpub\logs\LogFiles\W3SVC1\). O endereço IP real do cliente deverá aparecer.

Configurar o Apache

O Apache 2.4 e versões posteriores incluem o remoteip_module (mod_remoteip.so), que permite obter o endereço IP real do cliente.

Configurar o Tomcat

O Tomcat pode obter o endereço IP real do cliente ativando o recurso X-Forwarded-For.

1. Acesse o diretório de instalação do Tomcat e abra o arquivo de configuração tomcat/conf/server.xml.

2. Modifique a configuração de log do AccessLogValve conforme o exemplo abaixo:

   <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
   prefix="localhost_access_log." suffix=".txt"
   pattern="%{X-FORWARDED-FOR}i %l %u %t %r %s %b %D %q %{User-Agent}i %T" resolveHosts="false"/>

3. Reinicie o Tomcat.

   sudo systemctl restart tomcat

4. Acesse o site para validar a configuração e visualize os logs de acesso. O endereço IP real do cliente deverá aparecer.

   # Replace the following command with the actual Tomcat installation directory path and the actual log file
   tail -f /opt/tomcat/logs/localhost_access_log.2026-01-01.txt 

Configurar um cluster Kubernetes

Quando um cluster Kubernetes que utiliza o Nginx Ingress Controller é conectado ao WAF, o WAF adiciona o endereço IP real do cliente ao cabeçalho de requisição X-Forwarded-For. Por padrão, o Nginx Ingress Controller não confia nesse campo, impedindo que os contêineres de aplicação obtenham o IP real do cliente.

Siga as etapas abaixo para configurar o Nginx Ingress Controller.

1. Edite o ConfigMap do Ingress Controller:

   kubectl -n kube-system edit cm nginx-configuration

2. Adicione os seguintes itens de configuração ao campo data:

   compute-full-forwarded-for: "true"
   forwarded-for-header: "X-Forwarded-For"
   use-forwarded-headers: "true"

3. Salve e saia. A configuração entra em vigor automaticamente, sem necessidade de reiniciar os pods.

   Após concluir a configuração, o Ingress Controller identifica o primeiro endereço IP em X-Forwarded-For como o IP real do cliente e mantém esse valor ao encaminhar requisições.

Otimização avançada: Transmitir o IP real usando um cabeçalho personalizado

Em arquiteturas de rede complexas, depender exclusivamente do cabeçalho padrão X-Forwarded-For (XFF) traz riscos como falsificação e confusão de IPs em múltiplas camadas de proxy. Utilizar um cabeçalho HTTP personalizado para transmitir o IP real do cliente aumenta a segurança e o controle.

O exemplo a seguir demonstra como usar um cabeçalho personalizado para recuperar o IP real do cliente.

1. Configurar o CDN

   Por padrão, o CDN inclui o cabeçalho de requisição HTTP Ali-Cdn-Real-Ip nas requisições de back-to-origin, indicando o IP real do cliente no momento da conexão com o nó do CDN. Use Add a custom outbound request header para transmitir esse endereço IP ao WAF. A tabela abaixo mostra um exemplo de configuração no console do CDN.

   Parâmetro	Exemplo
   Operation	Add
   Request Header	Custom back-to-origin request header
   Header Name	Insira um nome personalizado, por exemplo, TrueIP
   Header Value	$http_Ali_Cdn_Real_Ip
   Allow Duplicates	Not Allowed
   Rule Condition	Não utilizado

2. Configurar o WAF

   Execute as duas configurações abaixo no console do WAF:

   • Is a Layer 7 proxy such as Anti-DDoS Proxy or CDN deployed in front of WAF: Ative esta opção para que o WAF identifique corretamente o endereço IP real do cliente.

   • Enable Traffic Tagging: Ative esta opção para permitir que o servidor de origem obtenha o endereço IP real do cliente.

   Para mais detalhes sobre como configurar essas opções, consulte Real client information.

   Parâmetro	Exemplo
   Is a Layer 7 proxy such as Anti-DDoS Proxy or CDN deployed in front of WAF	Selecione Yes e, em seguida, escolha [Recommended] Use the First IP Address in Specified Header Field as Actual IP Address of Client to Prevent X-Forwarded-For Forgery. Insira o Header Name definido na configuração do CDN, por exemplo, TrueIP.
   Enable Traffic Tagging	Selecione Originating IP Address e insira o Header Name definido na configuração do CDN, por exemplo, TrueIP.

3. Configurar o servidor de origem

   Tomando o Nginx como exemplo, edite o arquivo de configuração principal nginx.conf e adicione o conteúdo abaixo ao bloco http {}. Para mais informações, consulte Configure Nginx.

   http {
     # Trust request headers from the WAF back-to-origin IP addresses.
     # Replace the following placeholders with the WAF back-to-origin IP ranges you obtained from the console.
     # You must add all IP ranges. If any are missing, some requests might still log the WAF IP instead of the real client IP.
     set_real_ip_from    <ip_range1>;    
     set_real_ip_from    <ip_range2>;   
     ...
     set_real_ip_from    <ip_rangex>;
     # Tell Nginx to get the real IP from your custom header, TrueIP in this example.
     real_ip_header      TrueIP;
   }

   Recomendamos configurar o grupo de segurança do servidor de origem para permitir apenas tráfego proveniente dos intervalos de IP de back-to-origin do WAF. Isso garante que somente o WAF possa se comunicar com o servidor de origem, evitando que atacantes contornem o WAF e acessem diretamente o endereço IP público do servidor.

Qual a diferença entre a configuração de IP real no servidor de origem (descrita neste tópico) e a opção Is a Layer 7 proxy such as Anti-DDoS Proxy or CDN deployed in front of WAF no console do WAF?

• Configuração de IP real no servidor de origem (descrita neste tópico)

  • Finalidade: Após conectar seu domínio ao WAF via integração CNAME, esta configuração permite que o servidor de origem (como o Nginx) registre o endereço IP real do cliente em seus logs de acesso (como access.log) em vez do IP de back-to-origin do WAF.

  • Necessidade: Obrigatória apenas se você precisar visualizar ou processar o endereço IP real do cliente no servidor de origem.

• A opção Is a Layer 7 proxy such as Anti-DDoS Proxy or CDN deployed in front of WAF no console do WAF

  • Cenário aplicável: Outros proxies de camada 7 (como CDN ou Anti-DDoS Pro) estão implantados à frente do WAF.

  • Finalidade: Instrui o WAF a extrair o endereço IP real do cliente de um cabeçalho de requisição HTTP específico (como Ali-Cdn-Real-Ip ou X-Forwarded-For) para garantir que relatórios de segurança e identificação de ataques baseiem-se no IP de origem real.

  • Necessidade: Obrigatória apenas se houver um proxy de camada 7 implantado à frente do WAF. Se não existir nenhum proxy frontal, mantenha o valor padrão No.

O que é falsificação de X-Forwarded-For e como evitá-la?

A falsificação de X-Forwarded-For (XFF) refere-se a um ataque no qual o invasor constrói ou adultera o cabeçalho de requisição X-Forwarded-For em uma requisição HTTP para injetar um endereço IP de cliente falso, com o objetivo de contornar controles de acesso baseados em IP, auditoria de logs ou políticas de segurança. O X-Forwarded-For é um cabeçalho de requisição não padronizado que pode ser definido arbitrariamente pelos clientes. Se um service de backend confiar diretamente nesse campo sem validação, surgem riscos de segurança.

Exemplo: Comando de ataque de falsificação de XFF Um atacante pode usar o comando curl para forjar um cabeçalho X-Forwarded-For, falsificando o endereço IP como 1.2.3.4:

curl -H "X-Forwarded-For: 1.2.3.4" https://example.com/

Para evitar a falsificação de XFF, utilize um cabeçalho de requisição confiável personalizado para transmitir o IP real: Configure o CDN ou o WAF para usar um cabeçalho de requisição HTTP personalizado predefinido ao enviar requisições de volta ao servidor de origem. O servidor de origem então analisa apenas esse cabeçalho personalizado. Como esse cabeçalho é injetado por middleware confiável (como o WAF) e não pode ser controlado diretamente pelos clientes, a falsificação é efetivamente evitada.