Loading...

Практика

X-Forwarded-For и реальный IP посетителя за CDN

Поставьте CDN или любой reverse proxy перед сервером, и его логи заполнятся одними и теми же несколькими адресами: прокси, а не ваших посетителей. Реальный адрес всё ещё на месте — в заголовке запроса. Из этого руководства вы узнаете, как строится X-Forwarded-For, какому значению в нём можно доверять и почему, какие более простые заголовки добавляет cdn.com.tr и какие именно настройки нужны для nginx, Apache и Laravel.

9 мин чтения Средний Обновлено

X-Forwarded-For и реальный IP посетителя за CDN

Почему ваш сервер видит не тот IP

Без прокси браузер посетителя подключается прямо к вашему серверу, и адрес этого соединения — REMOTE_ADDR в PHP, $remote_addr в nginx — это адрес посетителя. Поставьте перед сервером CDN, балансировщик или любой reverse proxy, и соединение, которое принимает ваш сервер, приходит от прокси. Теперь каждая строка лога, каждый лимит запросов, каждая проверка «вход из нового места» видят адрес прокси.

Адрес посетителя не потерян. Прокси его видел и записывает в пересылаемый запрос, в заголовок. Вся тема сводится к двум вопросам: какой заголовок читать и когда ему верить — ведь заголовок это просто текст, а любой, кто может обратиться к вашему серверу напрямую, способен написать любой текст.

Как строится X-Forwarded-For

X-Forwarded-For (XFF) — это список через запятую. Каждый прокси, обрабатывающий запрос, берёт существующее значение и добавляет в конец адрес, от которого получил запрос. Посетитель с адресом 198.51.100.7, прошедший через один прокси, приходит на ваш сервер так:

X-Forwarded-For: 198.51.100.7

Через два прокси второй добавляет адрес первого:

X-Forwarded-For: 198.51.100.7, 203.0.113.20

А вот что важно для безопасности: прокси добавляет, но не проверяет, что там уже было. Посетитель может отправить собственный X-Forwarded-For: 1.2.3.4, и когда CDN добавит реальный адрес подключившегося, ваш сервер увидит:

X-Forwarded-For: 1.2.3.4, 198.51.100.7

Самое левое значение — это то, что напечатал посетитель. Значение, которому можно доверять, добавлено доверенным прокси — это крайнее справа, а при нескольких доверенных прокси подряд — первое справа значение, не являющееся одним из ваших прокси. Код, который берёт первое значение XFF как «IP клиента», может обмануть любой, у кого есть curl.

X-Real-IP и заголовки cdn.com.tr

X-Forwarded-For хранит историю; часто нужен один ответ. Для этого существуют заголовки с одним значением.

X-Real-IP многие прокси на базе nginx выставляют равным адресу принятого ими соединения. Наш edge выставляет его в каждом запросе.

X-CDN-Client-IP — это адрес посетителя, каким его увидел наш edge: одно значение, IPv4 или IPv6, которое edge записывает в каждом запросе. Заголовок с таким же именем, отправленный посетителем, заменяется, а не передаётся дальше. Это самый простой заголовок для чтения.

X-CDN-Client-Port — исходящий порт посетителя. Когда один публичный адрес делят многие пользователи — мобильные сети, carrier-grade NAT, — одного адреса недостаточно, чтобы определить посетителя; адрес вместе с портом определяет, и это нужно, когда строка лога должна указывать на одно соединение.

X-CDN-Edge-IP — адрес edge-сервера, к которому подключился посетитель; полезен, когда вы сопоставляете свои логи с нашими или записываете, где было установлено соединение.

Эти заголовки стандартно присутствуют в каждом запросе; включать ничего не нужно. Edge также отправляет X-Forwarded-For с добавленным адресом подключившегося, а также X-Forwarded-Proto, X-Forwarded-Host и X-Forwarded-Port для схемы, имени хоста и порта, которые использовал посетитель.

Доверяйте заголовку только от вашего CDN

Заголовок, который записывает edge, заслуживает доверия, только если запрос действительно прошёл через edge. Если ваш origin отвечает любому в интернете, злоумышленник может подключиться к нему напрямую и отправить X-CDN-Client-IP: 127.0.0.1 или любой другой адрес. Две меры закрывают эту брешь, и лучше всего они работают вместе.

Скажите веб-серверу, какие адреса — прокси. nginx, Apache и большинство фреймворков восстанавливают адрес клиента только для запросов с адресов, которые вы перечислили как доверенные; от всех остальных заголовки игнорируются. Перечислите адреса edge-серверов вашего аккаунта — актуальные адреса мы сообщаем по запросу.

Закройте origin для всех, кроме CDN. Требуйте секретный заголовок, имя и значение которого вы выбираете и добавляете в каждое правило доставки, либо клиентский сертификат edge через mTLS. Тогда прямой запрос вообще не доходит до вашего приложения, а пересылаемые заголовки в запросах, которые доходят, принадлежат edge.

Сделайте главным замком секретный заголовок или сертификат, а список адресов — вторым: они продолжают работать при любых изменениях адресов edge, тогда как список нужно поддерживать актуальным.

nginx: set_real_ip_from и real_ip_header

Модуль realip в nginx заменяет $remote_addr адресом из заголовка — но только когда соединение приходит с адреса, указанного в set_real_ip_from. После этого ваш access-лог, правила allow и deny и limit_req видят посетителя.

С X-CDN-Client-IP не нужно разбирать список. Если вы предпочитаете X-Forwarded-For — например, потому что между CDN и nginx стоит ваш собственный балансировщик, — используйте real_ip_header X-Forwarded-For; вместе с real_ip_recursive on; и перечислите в set_real_ip_from и адреса edge, и ваш балансировщик. Тогда nginx идёт по списку справа, пропускает каждый доверенный адрес и останавливается на первом недоверенном: это посетитель.

Сохраняйте в логе и исходный адрес подключившегося ($realip_remote_addr). Когда нужно знать, какой edge доставил запрос, он прямо там.

nginx: возвращаем адрес посетителя из 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

mod_remoteip в Apache решает ту же задачу. Включите его (a2enmod remoteip в Debian и Ubuntu), укажите заголовок и перечислите доверенные прокси. Используйте RemoteIPTrustedProxy для публичных адресов; RemoteIPInternalProxy предназначен для частных диапазонов.

Используйте %a в формате лога: при настроенном mod_remoteip это восстановленный адрес посетителя. Правила доступа вроде Require ip после настройки модуля тоже видят адрес посетителя.

Apache 2.4 с 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 и другие фреймворки: доверенные прокси

Фреймворки читают X-Forwarded-For сами, по тому же правилу: пересылаемые заголовки учитываются только от доверенных прокси. В Laravel 11 и новее вы объявляете их в bootstrap/app.php; тогда $request->ip() возвращает посетителя, а $request->secure() и генерируемые URL следуют X-Forwarded-Proto.

Laravel, через Symfony, читает X-Forwarded-For справа и пропускает доверенные адреса — ровно правило «крайнее справа доверенное». Не доверяйте * на origin, до которого интернет может достучаться напрямую: это заставляет фреймворк верить заголовкам любого клиента. Express (app.set('trust proxy', ...)) и Rails (config.action_dispatch.trusted_proxies) следуют той же идее под другими названиями.

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

Проверьте, что всё работает

Три быстрых теста подтверждают настройку.

Через CDN. Запросите страницу и посмотрите в access-лог: адрес должен быть вашим собственным публичным адресом, а не адресом edge.

Подделайте заголовок. Отправьте curl -H 'X-Forwarded-For: 1.2.3.4' -H 'X-CDN-Client-IP: 1.2.3.4' https://www.example.com/. Лог по-прежнему должен показывать ваш настоящий адрес: edge заменяет X-CDN-Client-IP и добавляет ваш адрес после отправленного вами значения XFF.

В обход CDN. Отправьте тот же запрос прямо на origin с --resolve. Если origin закрыт, запрос будет отклонён; если нет, лог должен показать ваш настоящий адрес, а не 1.2.3.4, потому что вашего адреса нет в списке доверенных. Если он показывает 1.2.3.4, список доверенных слишком широк.

Где важен реальный IP

Логи и аналитика

Access-логи, аналитика и отчёты о злоупотреблениях считают ваших посетителей, а не стоящие перед ними edge-серверы.

Лимиты запросов и баны

Лимиты по IP и блокировки в стиле fail2ban бьют по нарушителю, а не по всем, кто приходит к вам через тот же edge.

Расследования

Адрес, исходящий порт, время и адрес edge вместе указывают на одно соединение, даже за общими мобильными адресами.

Как настроить

Пошаговые руководства в справочном центре:

X-Forwarded-For: частые вопросы

Какое значение X-Forwarded-For — это IP клиента?

Крайнее справа значение, добавленное доверенным прокси. Значения левее уже были в заголовке, когда запрос дошёл до этого прокси, так что их мог написать посетитель. Когда перед сервером один CDN, это просто последнее значение.

Что происходит с заголовком X-Forwarded-For, который отправляет посетитель?

Edge сохраняет его и добавляет адрес, от которого получил запрос, как это делают прокси. Поэтому читать нужно крайнее справа значение — или X-CDN-Client-IP, одно значение, которое edge записывает сам и которое посетитель задать не может.

Чем X-Forwarded-For отличается от X-Real-IP?

X-Forwarded-For — это список, в который добавляет каждый прокси, поэтому он фиксирует весь путь. X-Real-IP — один адрес, выставленный одним прокси. Оба — соглашения; стандартный заголовок Forwarded (RFC 7239) несёт ту же информацию со строгим синтаксисом.

Зачем мне X-CDN-Client-Port?

Потому что много посетителей могут делить один публичный IP-адрес в мобильных сетях и за carrier-grade NAT. Исходящий порт вместе с адресом и временем различает этих посетителей, что нужно, когда строка лога должна указывать на одно соединение.

Можно ли доверять X-CDN-Client-IP с любого адреса?

Только если ваш origin не принимает трафик ни от кого, кроме CDN, и закрыт секретным заголовком или mTLS. Если до origin можно достучаться напрямую, этот заголовок может отправить кто угодно, поэтому ограничьте его ещё и адресами edge.

Где взять адреса edge, которым нужно доверять?

Актуальные адреса edge-серверов, связанных с вашим аккаунтом, мы сообщаем по запросу. Закройте origin ещё и секретным заголовком или mTLS, чтобы ваша защита не зависела от актуальности списка.