Все статьи

Gatekeeper 1.2: доступ по IP-адресу — офисная сеть без входа, лишние сети закрыты

Опубликовано · 8 мин чтения

Gatekeeper — это небольшой сервис, который стоит за обратным прокси и решает, кого пускать на закрытые страницы. Вход выполняется по одноразовому коду из письма или через OpenID Connect. Подробнее об этом мы писали в первой статье о Gatekeeper. Проект распространяется с открытым исходным кодом по лицензии MIT.

Версия 1.2.0 вышла 13 ноября 2026 года и добавляет две настройки: ip_allow и ip_deny. С первой из них сотрудник из офисной сети попадает на закрытую страницу без входа. Со второй выбранные сети не получают доступа вообще, и при любом конфликте запрет сильнее разрешения. Кроме того, версии 1.1.2 и 1.1.3 закрыли известные уязвимости в библиотеках и в версии Go, которые использует Gatekeeper. Обновление до 1.2 включает оба исправления.

Ниже разберём, как это устроено, на что надо обратить внимание в обратном прокси и что проверить перед включением.

Адреса и сети кратко

IP-адрес — это номер, по которому устройство находится в сети. Адреса бывают двух видов. IPv4 состоит из четырёх чисел, например 192.0.2.10. IPv6 длиннее и записывается шестнадцатеричными группами, например 2001:db8:1234::1. Настройки ip_allow и ip_deny принимают оба вида: и отдельные адреса, и целые сети.

Сеть записывают через косую черту. После адреса ставят слэш и число, которое показывает, сколько первых бит адреса зафиксировано. Для IPv4 это число от 0 до 32 (так описана нотация CIDR в RFC 4632). Запись 203.0.113.0/24 фиксирует первые три числа и охватывает адреса от 203.0.113.0 до 203.0.113.255. Одиночный адрес — это частный случай с /32. Префиксы IPv6 записываются так же: адрес, слэш и длина префикса, то есть число ведущих бит, которые образуют префикс (RFC 4291). Например, 2001:db8:1234::/48 — это сеть, у которой зафиксированы первые 48 бит.

Все адреса в этой статье — учебные. Для документации зарезервированы три блока IPv4: 192.0.2.0/24, 198.51.100.0/24 и 203.0.113.0/24 (RFC 5737). Для IPv6 зарезервирован префикс 2001:db8::/32 (RFC 3849). В интернете эти адреса встречаться не должны, поэтому ни один из примеров не указывает на чью-то настоящую сеть. В статье офисная сеть — это 203.0.113.0/24 или 2001:db8:1234::/48, а нежелательная сеть — 198.51.100.0/24.

ip_allow: офисная сеть без входа

На практике это выглядит так. У небольшой фирмы есть закрытый раздел с отчётами или предварительными версиями сайта. Сотрудникам каждый раз вводить одноразовый код неудобно, ведь они и так сидят в офисе, а адрес офисной сети известен. Эту сеть вы вносите в ip_allow, и запрос с такого адреса проходит без входа.

Есть одна особенность. Такой запрос проходит без вошедшего пользователя: Gatekeeper не устанавливает для него заголовок X-Gatekeeper-User. Если приложение за Gatekeeper читает этот заголовок, чтобы узнать, кто пришёл, для запросов из разрешённой сети оно имени не получит. Приложение должно спокойно справляться с запросом без этого заголовка.

Настройки можно задать на двух уровнях. На верхнем уровне они действуют для всех хостов. В записи отдельного хоста они действуют только для него. Так, офисную сеть можно пускать на страницы отчётов, а на другой хост по-прежнему пускать только после входа.

Например, если в ip_allow указана сеть 203.0.113.0/24, то запрос с адреса 203.0.113.57 пройдёт без входа. Запрос с 198.51.100.20 в эту запись не попадает и, как раньше, получит страницу входа.

Обновление до 1.2.0 не требует менять существующую конфигурацию. Проект повышает вторую цифру версии, когда что-то добавляется и при этом ничего менять не нужно. Если вы новые настройки не используете, всё работает как прежде.

ip_deny: нежелательные сети закрыты на любом пути

ip_deny работает в обратную сторону. Клиент с адресом из этого списка получает ответ 403 на любом пути. Для него нет ни страницы входа, ни письма с кодом, и неважно, какая сессия у него уже есть. Сеть закрыта полностью, а не только для входа.

Страницу входа здесь убирают осознанно. Если сеть вы закрыли, лучше не давать ей ни одной возможности: ни попробовать ввести код, ни запросить письмо. Например, вы внесли 198.51.100.0/24 в ip_deny. Любой запрос из этой сети получит 403, даже если раньше с этого адреса кто-то успел войти.

Если один адрес попадает сразу в оба списка, побеждает ip_deny. Допустим, в ip_allow стоит широкая сеть 203.0.113.0/24, а в ip_deny — один адрес из неё, 203.0.113.99. Остальные адреса сети проходят без входа, а 203.0.113.99 получает 403. Правило «запрет сильнее» защищает от ошибки: при случайном пересечении списков доступ не откроется.

Какие сети считать нежелательными, решаете вы. Gatekeeper лишь выполняет ваш список.

Отдельно напомним: с версии 1.0.0 Gatekeeper ограничивает частоту запросов с одного адреса клиента. Адреса IPv6 учитываются по /64, а целая сеть /48 — не более 16 раз. Это другой механизм, он работает независимо от списков.

Учитывается только адрес, который называет доверенный прокси

Оба списка оценивают только адрес клиента, который сообщает доверенный прокси. Объясним, почему это важно.

Gatekeeper стоит за обратным прокси: nginx обращается к нему через auth_request, а Traefik — через forwardAuth. Сам Gatekeeper видит соединение от прокси, а не от посетителя. Настоящий адрес посетителя прокси передаёт в заголовках, чаще всего в X-Forwarded-For. Но заголовок — это просто текст, который может написать кто угодно.

MDN описывает это прямо. Любое применение X-Forwarded-For в целях безопасности, например ограничение частоты запросов или управление доступом по IP, должно использовать только адреса, добавленные доверенным прокси. Любая часть заголовка, добавленная не доверенным прокси, может быть подделана. Если же использовать ненадёжные значения, возможны обход ограничения частоты, обход контроля доступа, исчерпание памяти и другие проблемы с безопасностью и доступностью.

Подделка выглядит так. Злоумышленник сам ставит в начало заголовка выдуманный адрес, скажем адрес вашей офисной сети. Доверенный прокси добавляет настоящий адрес в конец списка. Если код читает первый адрес слева, он берёт подделку и впускает чужого человека как своего. Поэтому адрес должен определять только тот прокси, которому вы доверяете, а не то, что прислал клиент.

MDN добавляет ещё одно условие. Если сервер доступен напрямую из интернета, пусть даже он стоит и за доверенным обратным прокси, ни одной части списка X-Forwarded-For нельзя считать надёжной для целей безопасности. Значит, защищаемый сервис должен быть доступен только через обратный прокси.

Доверие к заголовкам настраивается в самом обратном прокси. Ниже речь идёт именно о его настройках, а не о настройках Gatekeeper.

У nginx для этого есть директива set_real_ip_from. Она задаёт доверенные адреса, о которых известно, что они присылают правильные заменяющие адреса. Можно указать адрес или диапазон CIDR. Директива real_ip_header определяет, значение какого заголовка заменит адрес клиента. По умолчанию это X-Real-IP.

У Traefik есть параметр forwardedHeaders.trustedIPs. В нём перечисляют IP-адреса или диапазоны CIDR, от которых Traefik доверяет заголовкам X-Forwarded-*. Параметр forwardedHeaders.insecure включает доверие всегда, но документация рекомендует его только для тестов, не для рабочей среды.

Пропуска для всех не будет: 0.0.0.0/0 и ::/0

Запись 0.0.0.0/0 означает все адреса IPv4, а ::/0 — все адреса IPv6. Если внести такую запись в ip_allow, защита фактически отключится: пройти без входа сможет каждый. Такое обычно получается по ошибке, например при опечатке в длине префикса.

Gatekeeper такие записи в ip_allow отказывается принимать. Это защита от случайной ошибки.

Исправления безопасности в 1.1.2 и 1.1.3

Кроме новых настроек, мы советуем обновиться и ради двух небольших релизов, которые вышли до 1.2.

Версия 1.1.2 от 3 ноября 2026 года обновила библиотеку go-jose до 4.1.8. Обновление закрывает три бюллетеня безопасности, касавшихся версии 4.1.4. Первый — GHSA-mgcc-cww5-fp2q, с высокой степенью серьёзности: отказ в обслуживании при разборе набора ключей с ключами RSA. Два других — GHSA-vvm8-gf78-28g4 и GHSA-4w3g-jfj2-cw2q, средней серьёзности: аварийные остановки (паника) при разборе JSON и при обработке CBC-HMAC.

Есть и практическое следствие. Начиная с go-jose 4.1.6 ключ RSA в наборе ключей провайдера может иметь не более 4096 бит. Распространённый провайдер использует 2048 или 4096 бит, так что на практике это, как правило, ничего не меняет. Но если вы входите через OpenID Connect, стоит знать об этом пределе.

Версия 1.1.3 от 13 ноября 2026 года перешла на Go 1.27.4. Она закрывает GO-2026-6859 в net/http. Это аварийное завершение сервера HTTP/1 из-за состояния гонки в MaxBytesReader, о котором govulncheck сообщает для путей кода Gatekeeper. Кроме того, исправлены проблемы безопасности в команде go, компиляторе и компоновщике.

Образы собираются для каждого релиза с тегами X.Y.Z, X.Y и X, а тег latest переносится на новую версию. Образы лежат на Docker Hub и в реестре GitLab для linux/amd64 и linux/arm64. Обновление до 1.2 включает оба исправления.

Чек-лист перед включением

Перед тем как включать списки адресов, пройдите по пунктам:

  • Запишите офисную сеть вместе с префиксом (например, вида 203.0.113.0/24) и проверьте у провайдера, какие адреса у вас на самом деле используются. Для IPv6 запишите свой префикс отдельно.
  • Убедитесь, что защищаемый сервис доступен только через обратный прокси, а не напрямую из интернета (об этом предупреждает MDN).
  • Проверьте, что обратный прокси доверяет пересылаемым заголовкам только от известных прокси: в nginx это set_real_ip_from, в Traefik — forwardedHeaders.trustedIPs. Режим forwardedHeaders.insecure в рабочей среде не используйте.
  • Проверьте, что приложение за Gatekeeper справляется с запросами без заголовка X-Gatekeeper-User, ведь для адресов из ip_allow его не будет.
  • Решите, нужны ли списки на верхнем уровне для всех хостов или только в записях отдельных хостов.
  • Проверьте конфигурацию командой gatekeeper check до перезапуска.
  • Обновитесь до версии 1.2 или новее: так вы получите и новые настройки, и исправления из 1.1.2 и 1.1.3.

Списки адресов не заменяют вход везде. Это удобное дополнение для случаев, когда сеть известна и ей можно доверять.

Как помогает epicsoft

В наш хостинг входит контроль доступа к внутренним страницам. Gatekeeper защищает у нас отчёты Lighthouse и SEO для сайтов epicsoft, а также предварительные версии новых релизов. Мы с радостью настроим его и для ваших страниц, как и сказано в первой статье.

Источники

Готовы к следующему шагу?

Лучшего момента, чтобы начать, ещё не было. Расскажите нам о своём проекте.

Связаться с нами