Loading...

Guía práctica

X-Forwarded-For y la IP real del visitante detrás de un CDN

Ponga un CDN o cualquier reverse proxy delante de un servidor y sus logs se llenarán con las mismas pocas direcciones: las del proxy, no las de sus visitantes. La dirección real sigue ahí, en una cabecera de la solicitud. Esta guía explica cómo se construye X-Forwarded-For, qué valor de ella es de fiar y por qué, las cabeceras más sencillas que añade cdn.com.tr y los ajustes exactos para nginx, Apache y Laravel.

9 min de lectura Intermedio Actualizado

X-Forwarded-For y la IP real del visitante detrás de un CDN

Por qué su servidor ve la IP equivocada

Sin proxy, el navegador de un visitante se conecta directamente a su servidor, y la dirección de esa conexión —REMOTE_ADDR en PHP, $remote_addr en nginx— es la del visitante. Ponga delante un CDN, un balanceador de carga o cualquier reverse proxy y la conexión que acepta su servidor procede del proxy. Cada línea de log, cada límite de tasa, cada comprobación de «inicio de sesión desde una ubicación nueva» ve ahora la dirección del proxy.

La dirección del visitante no se pierde. El proxy la vio y la escribe en la solicitud que reenvía, en una cabecera. Todo el asunto se reduce a dos preguntas: qué cabecera leer y cuándo creerla, porque una cabecera es solo texto, y cualquiera que pueda llegar directamente a su servidor puede escribir el texto que quiera.

Cómo se construye X-Forwarded-For

X-Forwarded-For (XFF) es una lista separada por comas. Cada proxy que gestiona la solicitud toma el valor existente y añade al final la dirección de la que recibió la solicitud. Un visitante en 198.51.100.7 que pasa por un proxy llega a su servidor así:

X-Forwarded-For: 198.51.100.7

Con dos proxies, el segundo añade la dirección del primero:

X-Forwarded-For: 198.51.100.7, 203.0.113.20

Aquí está lo que importa para la seguridad: un proxy añade; no comprueba lo que ya había. Un visitante puede enviar su propio X-Forwarded-For: 1.2.3.4, y cuando el CDN añade la dirección real desde la que se conecta, su servidor ve:

X-Forwarded-For: 1.2.3.4, 198.51.100.7

El valor de más a la izquierda es lo que escribió el visitante. El valor en el que puede confiar es el añadido por el proxy de confianza: el más a la derecha o, con varios proxies de confianza seguidos, el primer valor desde la derecha que no sea uno de sus propios proxies. El código que toma el primer valor de XFF como «la IP del cliente» puede ser engañado por cualquiera con curl.

X-Real-IP y las cabeceras de cdn.com.tr

X-Forwarded-For lleva un historial; a menudo solo se quiere una respuesta. Para eso existen las cabeceras de valor único.

X-Real-IP la establecen muchos proxies basados en nginx con la dirección de la conexión que aceptaron. Nuestro edge la establece en cada solicitud.

X-CDN-Client-IP es la dirección del visitante tal como la vio nuestro edge: un único valor, IPv4 o IPv6, escrito por el edge en cada solicitud. Una cabecera del mismo nombre enviada por el visitante se sustituye, no se transmite. Es la cabecera más sencilla de leer.

X-CDN-Client-Port es el puerto de origen del visitante. Donde muchos usuarios comparten una dirección pública —redes móviles, CGNAT—, la dirección sola no identifica a un visitante; dirección más puerto sí, y eso es lo que necesita cuando una línea de log debe señalar una única conexión.

X-CDN-Edge-IP es la dirección del servidor edge al que se conectó el visitante, útil cuando cruza sus logs con los nuestros o registra dónde se realizó una conexión.

Estas cabeceras son estándar en cada solicitud; no hay nada que activar. El edge también envía X-Forwarded-For con la dirección de conexión añadida, y X-Forwarded-Proto, X-Forwarded-Host y X-Forwarded-Port con el esquema, el nombre de host y el puerto que usó el visitante.

Confíe en la cabecera solo si viene de su CDN

Una cabecera que escribe el edge es de fiar solo cuando la solicitud realmente pasó por el edge. Si su origen responde a cualquiera en internet, un atacante puede conectarse directamente a él y enviar X-CDN-Client-IP: 127.0.0.1 o la dirección que quiera. Dos medidas cierran esa brecha, y funcionan mejor juntas.

Indique a su servidor web qué direcciones son proxies. nginx, Apache y la mayoría de los frameworks restauran la dirección del cliente solo para las solicitudes que vienen de direcciones que usted enumera como de confianza; de cualquier otra, las cabeceras se ignoran. Enumere las direcciones del edge de su cuenta: le indicamos las direcciones actuales cuando lo solicite.

Bloquee el origen al CDN. Exija una cabecera secreta cuyo nombre y valor elige usted y que añade a cada regla de entrega, o exija el certificado de cliente del edge con mTLS. Así una solicitud directa nunca llega a su aplicación, y las cabeceras reenviadas de las solicitudes que sí llegan son las del edge.

Haga de la cabecera secreta o del certificado el cierre principal y de la lista de direcciones el segundo: siguen funcionando aunque cambien las direcciones del edge, mientras que una lista hay que mantenerla al día.

nginx: set_real_ip_from y real_ip_header

El módulo realip de nginx sustituye $remote_addr por la dirección de una cabecera, pero solo cuando la conexión viene de una dirección enumerada en set_real_ip_from. Después, su log de acceso, las reglas allow y deny y limit_req ven al visitante.

Con X-CDN-Client-IP no hay lista que analizar. Si prefiere X-Forwarded-For —por ejemplo porque hay un balanceador propio entre el CDN y nginx—, use real_ip_header X-Forwarded-For; con real_ip_recursive on; y enumere en set_real_ip_from tanto las direcciones del edge como su balanceador. nginx recorre entonces la lista desde la derecha, omite cada dirección de confianza y se detiene en la primera que no lo es: el visitante.

Conserve también en el log la dirección de conexión original ($realip_remote_addr). Cuando necesite saber qué edge entregó una solicitud, está ahí mismo.

nginx: restaurar la dirección del visitante desde el CDN

# in http {} or server {}
# the edge addresses for your account (placeholders)
set_real_ip_from 203.0.113.0/24;
set_real_ip_from 2001:db8:100::/48;
real_ip_header   X-CDN-Client-IP;

log_format cdn '$remote_addr:$http_x_cdn_client_port via $realip_remote_addr '
               '[$time_local] "$request" $status $body_bytes_sent';
access_log /var/log/nginx/access.log cdn;

Apache: mod_remoteip

El mod_remoteip de Apache hace el mismo trabajo. Actívelo (a2enmod remoteip en Debian y Ubuntu), indique la cabecera y enumere los proxies de confianza. Use RemoteIPTrustedProxy para direcciones públicas; RemoteIPInternalProxy está pensado para rangos privados.

Use %a en el formato del log: con mod_remoteip configurado es la dirección restaurada del visitante. Las reglas de acceso como Require ip también ven la dirección del visitante una vez configurado el módulo.

Apache 2.4 con mod_remoteip

RemoteIPHeader        X-CDN-Client-IP
# the edge addresses for your account (placeholders)
RemoteIPTrustedProxy  203.0.113.0/24
RemoteIPTrustedProxy  2001:db8:100::/48

LogFormat "%a %{X-CDN-Client-Port}i %l %u %t \"%r\" %>s %b" cdn
CustomLog ${APACHE_LOG_DIR}/access.log cdn

Laravel y otros frameworks: proxies de confianza

Los frameworks leen X-Forwarded-For por sí mismos, con la misma regla: las cabeceras reenviadas solo cuentan si vienen de proxies de confianza. En Laravel 11 y posteriores se declaran en bootstrap/app.php; $request->ip() devuelve entonces al visitante, y $request->secure() y las URL generadas siguen a X-Forwarded-Proto.

Laravel, a través de Symfony, lee X-Forwarded-For desde la derecha y omite las direcciones de confianza: exactamente la regla del valor de confianza más a la derecha. No confíe en * en un origen al que internet puede llegar directamente; eso le dice al framework que crea las cabeceras de cualquier cliente. Express (app.set('trust proxy', ...)) y Rails (config.action_dispatch.trusted_proxies) siguen la misma idea con otros nombres.

bootstrap/app.php (Laravel 11+)

use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(
        at: ['203.0.113.0/24', '2001:db8:100::/48'], // edge addresses (placeholders)
        headers: Request::HEADER_X_FORWARDED_FOR
            | Request::HEADER_X_FORWARDED_HOST
            | Request::HEADER_X_FORWARDED_PORT
            | Request::HEADER_X_FORWARDED_PROTO,
    );
})

// anywhere in the application
$ip   = $request->ip();                         // the visitor
$port = $request->header('X-CDN-Client-Port');  // the visitor's source port

Compruebe que funciona

Tres pruebas rápidas confirman la configuración.

A través del CDN. Solicite una página y mire su log de acceso: la dirección debe ser su propia dirección pública, no la de un edge.

Falsifíquela. Envíe curl -H 'X-Forwarded-For: 1.2.3.4' -H 'X-CDN-Client-IP: 1.2.3.4' https://www.example.com/. El log debe seguir mostrando su dirección real: el edge sustituye X-CDN-Client-IP y añade su dirección después del valor de XFF que usted envió.

Rodee el CDN. Envíe la misma solicitud directamente al origen con --resolve. Si el origen está bloqueado, la solicitud es rechazada; si no lo está, el log debe mostrar su dirección real y no 1.2.3.4, porque su dirección no está en la lista de confianza. Si muestra 1.2.3.4, la lista de confianza es demasiado amplia.

Dónde importa la IP real

Logs y analítica

Los logs de acceso, la analítica y los informes de abuso cuentan a sus visitantes, no a los servidores edge que tienen delante.

Límites de tasa y bloqueos

Los límites por IP y los bloqueos al estilo fail2ban alcanzan al abusador en lugar de a todos los que le llegan por el mismo edge.

Investigaciones

Dirección, puerto de origen, hora y dirección del edge juntos señalan una única conexión, incluso detrás de direcciones móviles compartidas.

Cómo configurarlo

Guías paso a paso en el centro de ayuda:

Preguntas frecuentes sobre X-Forwarded-For

¿Qué valor de X-Forwarded-For es la IP del cliente?

El valor más a la derecha añadido por un proxy de confianza. Los valores a su izquierda ya estaban en la cabecera cuando la solicitud llegó a ese proxy, así que puede haberlos escrito el visitante. Con un solo CDN delante de su servidor, es simplemente el último valor.

¿Qué ocurre con una cabecera X-Forwarded-For que envía el visitante?

El edge la conserva y añade al final la dirección de la que recibió la solicitud, como hacen los proxies. Por eso se lee el valor más a la derecha, o X-CDN-Client-IP, un valor único que escribe el propio edge y que un visitante no puede establecer.

¿Cuál es la diferencia entre X-Forwarded-For y X-Real-IP?

X-Forwarded-For es una lista a la que añade cada proxy, así que registra todo el recorrido. X-Real-IP es una única dirección establecida por un proxy. Ambas son convenciones; la cabecera estándar Forwarded (RFC 7239) lleva la misma información con una sintaxis más estricta.

¿Para qué necesitaría X-CDN-Client-Port?

Porque muchos visitantes pueden compartir una misma dirección IP pública en redes móviles y detrás de CGNAT. El puerto de origen, junto con la dirección y la hora, distingue a esos visitantes, que es lo que necesita cuando una línea de log debe señalar una sola conexión.

¿Puedo confiar en X-CDN-Client-IP desde cualquier dirección?

Solo cuando su origen no acepta tráfico salvo el del CDN, bloqueado con una cabecera secreta o mTLS. Si se puede llegar al origen directamente, cualquiera puede enviar esa cabecera, así que restrinja también a las direcciones del edge.

¿De dónde saco las direcciones del edge en las que confiar?

Le indicamos las direcciones actuales de los servidores edge vinculados a su cuenta cuando lo solicite. Bloquee también el origen con una cabecera secreta o mTLS, para que su protección no dependa de mantener una lista al día.