Skip to main content

XForwardedFor | XForwardedProto | Design de API's | CSharp

  • XForwardedFor | XForwardedProto | Design de API's | CSharp

📄 Documentação — Configuração de ForwardedHeaders no ASP.NET Core​

Essa configuração habilita o ASP.NET Core a interpretar corretamente os headers de encaminhamento enviados por proxies/reverse proxies (ex.: Nginx, Traefik, Kubernetes Ingress, Load Balancer).

Com isso, sua aplicação consegue obter informações reais do cliente, como:

  • IP real do cliente
  • Protocolo original (HTTP/HTTPS)

📌 Código configurado​

services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;

    options.KnownNetworks.Clear();
    options.KnownProxies.Clear();

    options.KnownNetworks.Add(new AspNetIPNetwork(IPAddress.Parse("172.16.0.0"), 12));
});

✅ O que cada parte faz​

1) ForwardedHeaders = XForwardedFor | XForwardedProto​

Indica quais headers a aplicação deve confiar e processar:

  • X-Forwarded-For → contém o IP original do cliente
  • X-Forwarded-Proto → indica se o cliente usou http ou https

📌 Resultado:

  • HttpContext.Connection.RemoteIpAddress pode virar o IP real do cliente
  • HttpRequest.Scheme pode virar "https" mesmo que o proxy converse com o backend via HTTP

2) KnownNetworks.Clear() e KnownProxies.Clear()​

O ASP.NET Core só aplica os forwarded headers se o proxy for confiável.

Essas duas linhas limpam a lista padrão de proxies confiáveis.

✅ Utilidade:

  • Permite configurar manualmente quais redes/proxies serão aceitos
  • Evita confiar em proxies desconhecidos por padrão

⚠️ Importante: Se você limpar e não adicionar nenhum KnownNetwork/KnownProxy válido, a aplicação pode ignorar os forwarded headers.

3) KnownNetworks.Add(172.16.0.0/12)​

Essa linha define uma rede como “confiável” para encaminhar headers:

options.KnownNetworks.Add(new AspNetIPNetwork(IPAddress.Parse("172.16.0.0"), 12));

Isso inclui o range privado:

✅ 172.16.0.0 até 172.31.255.255

📌 Esse range é muito comum em:

  • Docker
  • Kubernetes
  • Redes internas corporativas

Ou seja: qualquer proxy dentro dessa rede poderá informar X-Forwarded-For e X-Forwarded-Proto, e a aplicação vai aceitar.

✅ Onde usar isso no pipeline​

Além de configurar no DI, é obrigatório habilitar no app:

app.UseForwardedHeaders();

📌 O ideal é chamar logo no início, antes de UseAuthentication, UseAuthorization, etc.

✅ Benefícios práticos (exemplos)​

Após ativar isso:

✅ IP real:

var ip = HttpContext.Connection.RemoteIpAddress;

✅ Detectar HTTPS corretamente:

var scheme = HttpContext.Request.Scheme; // http/https

✅ Melhor tracing/logs:

  • client.ip
  • http.scheme
  • auditoria por IP real

⚠️ Atenção / riscos de segurança​

Se você aceitar forwarded headers de redes erradas, um cliente pode “forjar” o IP enviando:

X-Forwarded-For: 1.2.3.4

Por isso: ✅ só adicione redes/proxies que você confia ✅ evite deixar tudo liberado em produção

✅ Quando essa configuração é necessária​

Use quando seu sistema está atrás de:

  • Reverse Proxy
  • API Gateway
  • Kubernetes Ingress
  • Cloud Load Balancer
  • Docker (com bridge network)