Настройка SSO для любого приложения через oauth2-proxy
Используйте oauth2-proxy для внедрения SSO в приложения без встроенной авторизации. Узнайте, как настроить forward auth в Nginx или Traefik и избежать ошибок с cookie.
Forward auth: как добавить SSO в приложение без собственной системы авторизации
oauth2-proxy позволяет реализовать единый вход (SSO) для приложения, в котором нет собственной системы авторизации. Это работает за счет того, что обратный прокси-сервер перед приложением перехватывает каждый запрос, запрашивает у oauth2-proxy информацию о наличии валидной сессии и передает запрос вышестоящему приложению только в случае положительного ответа. Код приложения при этом не меняется, так как приложение не участвует в проверке.
Проверка представляет собой дополнительный HTTP-запрос. Прокси отправляет копию заголовков входящего запроса в /oauth2/auth и считывает код ответа. Код 202 означает успешную проверку, поэтому прокси пересылает исходный запрос приложению. Код 401 означает отсутствие валидной сессии, поэтому прокси перенаправляет браузер на /oauth2/sign_in, где по умолчанию отображается страница входа. /oauth2/start инициирует процесс входа через OpenID Connect (OIDC) у вашего провайдера идентификации; skip_provider_button = true позволяет /oauth2/sign_in запускать этот процесс автоматически. OIDC — это уровень идентификации, построенный поверх OAuth 2.0, а провайдером выступает любая система, которую вы уже используете для авторизации.
У этого шаблона есть свое название в каждом обратном прокси-сервере. В Nginx эта директива называется auth_request. В Traefik это middleware forwardAuth. В Caddy используется forward_auth. Сервис, отвечающий на подзапросы, также может быть заменен. oauth2-proxy является популярным выбором, так как он поддерживает стандартный OIDC и не требует собственной базы данных.
Определите границы доверия перед написанием конфигурации
После успешной проверки oauth2-proxy возвращает данные об идентификации в заголовках ответа, а обратный прокси копирует их в запрос к upstream-серверу. При включенном set_xauthrequest вы получаете X-Auth-Request-User и X-Auth-Request-Email. Приложение считывает эти заголовки и доверяет им.
Это вся модель безопасности, поэтому сформулируем следствие в явном виде. Любой объект, способный установить TCP-соединение с портом приложения, может самостоятельно задать эти заголовки и выдать себя за любого пользователя. Одиночный curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ означает полный обход защиты, если запрос достигает приложения напрямую.
Следовательно, приложение не должно быть доступно иначе, как через прокси. В Docker Compose удалите маппинг ports: из сервиса приложения и оставьте его только во внутренней сети, чтобы только контейнер с прокси мог подключаться к нему. На обычном хосте привяжите приложение к 127.0.0.1:3000 вместо 0.0.0.0:3000. Затем проверьте, что именно вы выставили наружу:
sudo ss -tlnp | grep 3000Строка, содержащая 0.0.0.0:3000, означает, что приложение отвечает на публичном IP-адресе и ваш шлюз является лишь декорацией. 127.0.0.1:3000 — это то, что вам нужно. Правило межсетевого экрана является полезным вторым уровнем защиты, но адрес привязки — это то, что останется в силе, даже если другой инструмент сбросит ваш набор правил.
Установка oauth2-proxy
По состоянию на октябрь 2026 года актуальным релизом является v7.15.5, выпущенный 1 октября 2026 года. Он устраняет две критические уязвимости, одна из которых позволяет обойти skip_auth_routes и затрагивает все версии после v7.5.0, поэтому не устанавливайте более старые версии. Установите бинарный файл и проверьте загрузку:
cd /tmp
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz
curl -fsSLO https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v7.15.5/oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
sha256sum -c oauth2-proxy-v7.15.5.linux-amd64.tar.gz-sha256sum.txt
tar -xzf oauth2-proxy-v7.15.5.linux-amd64.tar.gz
sudo install -m 755 oauth2-proxy-v7.15.5.linux-amd64/oauth2-proxy /usr/local/bin/oauth2-proxy
oauth2-proxy --versionsha256sum -c должен вывести строку, заканчивающуюся на OK. Если выводится FAILED, остановитесь и загрузите файл заново, вместо того чтобы запускать бинарный файл.
В Docker используется образ quay.io/oauth2-proxy/oauth2-proxy, и вам следует зафиксировать тег: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Использование тега latest превращает плановую операцию docker compose pull в незапланированное обновление процесса, который защищает все приложения на сервере.
Генерация секрета cookie
Сессионный cookie шифруется, а cookie_secret выступает в роли ключа. Ключ шифрования должен иметь длину ровно 16, 24 или 32 байта, так как он используется в качестве ключа AES (Advanced Encryption Standard). oauth2-proxy принимает значение в формате URL-safe base64, которое при декодировании дает одну из указанных длин, либо «сырой» секрет соответствующей длины; в противном случае сервис отказывается запускаться, выдавая при старте ошибку с упоминанием секрета cookie. Приведенная ниже команда создает 44-символьное значение, кодирующее 32-байтовый ключ.
openssl rand -base64 32 | tr -- '+/' '-_'Использование tr не является формальностью. Эта часть команды преобразует стандартный base64 в алфавит, безопасный для URL (URL-safe), который oauth2-proxy использует при декодировании секрета.
Для этого значения действуют два правила. Используйте уникальный секрет для каждого развертывания. Если вы запускаете несколько экземпляров oauth2-proxy в рамках одного домена, задайте им всем одинаковый секрет, так как cookie, зашифрованный одним экземпляром, должен быть доступен для чтения остальным.
Настройка oauth2-proxy
Храните параметры в файле, а не в длинной командной строке, чтобы client secret не отображался в выводе ps.
# /etc/oauth2-proxy/oauth2-proxy.cfg
http_address = "127.0.0.1:4180"
reverse_proxy = true
provider = "oidc"
oidc_issuer_url = "https://id.example.com/application/o/myapp/"
client_id = "REPLACE_ME"
client_secret = "REPLACE_ME"
redirect_url = "https://app.example.com/oauth2/callback"
cookie_secret = "REPLACE_ME"
cookie_secure = true
cookie_domains = [".example.com"]
whitelist_domains = [".example.com"]
email_domains = ["*"]
set_xauthrequest = true
upstreams = ["static://202"]reverse_proxy = true указывает oauth2-proxy доверять заголовкам X-Forwarded-* от прокси, стоящего перед ним. Без этого параметра oauth2-proxy воспринимает адрес прокси как адрес клиента и может ошибочно определить, поступил ли запрос по HTTPS.
trusted_proxy_ips ограничивает список узлов, которые могут передавать эти заголовки. По умолчанию доверие оказывается всем источникам, что безопасно в данном случае только потому, что http_address удерживает oauth2-proxy на 127.0.0.1. Если oauth2-proxy работает в сети Docker, установите здесь адрес вашего reverse proxy.
upstreams = ["static://202"] заставляет oauth2-proxy отвечать кодом 202 на аутентифицированный запрос и не проксировать трафик, что и требуется для forward auth, так как проксированием занимается reverse proxy. Другой вариант развертывания предполагает размещение oauth2-proxy непосредственно в пути запроса с использованием upstreams = ["http://127.0.0.1:3000"] и без auth_request. Это проще для одного приложения, но не масштабируется до десяти.
email_domains = ["*"] разрешает доступ для всех адресов, которые аутентифицирует ваш провайдер. Ограничьте этот список своим доменом или, что лучше, настройте ограничение доступа через привязку к группам на стороне провайдера, так как именно там вы управляете пользователями.
Запустите сервис через systemd от имени отдельного пользователя:
# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target
[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.targetsudo useradd --system --no-create-home --shell /usr/sbin/nologin oauth2-proxy
sudo install -d -m 750 /etc/oauth2-proxy
sudo chown -R oauth2-proxy:oauth2-proxy /etc/oauth2-proxy
sudo chmod 600 /etc/oauth2-proxy/oauth2-proxy.cfg
sudo systemctl daemon-reload
sudo systemctl enable --now oauth2-proxy
curl -s http://127.0.0.1:4180/ping/ping и вывод OK означают, что процесс запущен и загрузил конфигурацию. Это встроенный endpoint для проверки работоспособности oauth2-proxy, который не требует сессии. Если ответа нет, изучите journalctl -u oauth2-proxy -n 50: неверный URL издателя (issuer URL) или неправильная длина секрета cookie приводят к сбою при запуске, о чем сервис сообщает в логах.
Регистрация URI перенаправления у вашего провайдера
Создайте OIDC-приложение в панели управления вашего провайдера и установите его URI перенаправления в точном соответствии с redirect_url из конфигурации: https://app.example.com/oauth2/callback. «В точном соответствии» означает, что схема, хост, порт и путь должны совпадать символ в символ. Наличие или отсутствие завершающего слэша делает URI другим.
Это самая частая причина сбоев во всей настройке, и ошибка возникает еще до того, как в процесс включается oauth2-proxy. Провайдер отклоняет запрос на авторизацию и выводит собственную страницу ошибки, поэтому в логах oauth2-proxy ничего не появляется. Признак проблемы находится в адресной строке: браузер всё ещё находится на домене провайдера, а строка запроса содержит error=invalid_request или названия страниц redirect_uri. Если вы видите это, исправляйте запись приложения у провайдера, а не конфигурацию прокси.
Скопируйте URL издателя (issuer URL) из панели провайдера, а не вводите его вручную. oauth2-proxy добавляет /.well-known/openid-configuration к oidc_issuer_url и запрашивает этот документ обнаружения (discovery document) при запуске. Проверьте его самостоятельно:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400Наличие ключа authorization_endpoint в JSON — это первая проверка; значение issuer в документе также должно в точности совпадать с oidc_issuer_url. Ошибка 404 или HTML-страница с ошибкой означают, что путь указан неверно, и oauth2-proxy не сможет запуститься из-за этой же ошибки 404. Если вы ещё не выбрали провайдера, сравнение Keycloak, Authentik и Zitadel поможет оценить преимущества и недостатки, а запуск Authentik в качестве собственного SSO-сервера содержит пошаговое руководство по настройке провайдера для данного сценария.
Nginx: auth_request
Nginx выполняет сквозную аутентификацию с помощью auth_request, который инициирует внутренний подзапрос и выполняет ветвление в зависимости от его кода состояния.
# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name app.example.com;
location /oauth2/ {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Auth-Request-Redirect $request_uri;
}
location = /oauth2/auth {
proxy_pass http://127.0.0.1:4180;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Uri $request_uri;
proxy_set_header Content-Length "";
proxy_pass_request_body off;
}
location / {
auth_request /oauth2/auth;
error_page 401 = @oauth2_signin;
auth_request_set $user $upstream_http_x_auth_request_user;
auth_request_set $email $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
proxy_set_header X-Email $email;
auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
}Здесь важны три детали. proxy_pass_request_body off с пустым Content-Length предотвращает передачу тела запроса на endpoint аутентификации, которому нужны только заголовки.
Пара auth_request_set $auth_cookie и add_header Set-Cookie передает обновленный session cookie обратно в браузер. Если их не указать, cookie_refresh молча не выполнит действие, так как nginx отбрасывает Set-Cookie подзапроса, и браузер сохранит старое значение до истечения сессии. Эта пара обрабатывает один cookie; для разделенных session cookies потребуется дополнительная обработка остальных частей или использование Redis для хранения сессий.
error_page 401 = @oauth2_signin превращает неудачную проверку в перенаправление на страницу входа. Без этой директивы неавторизованный посетитель увидит пустую страницу 401 Authorization Required и не сможет продолжить работу.
Всегда проверяйте конфигурацию перед перезагрузкой:
sudo nginx -t && sudo systemctl reload nginxЕсли окружающие директивы вам незнакомы, структура конфигурации обратного прокси nginx описывает уровень, лежащий в основе этого механизма.
Traefik: middleware forwardAuth
Для выполнения этой задачи Traefik требует два middleware. Один выполняет проверку. Второй отображает страницу входа, если проверка не пройдена.
# dynamic configuration
http:
middlewares:
oauth-auth:
forwardAuth:
address: https://oauth.example.com/oauth2/auth
trustForwardHeader: true
oauth-errors:
errors:
status:
- "401-403"
service: oauth-backend
query: "/oauth2/sign_in?rd={url}"Подключите оба к роутеру, который обслуживает ваше приложение, указав oauth-errors перед oauth-auth. Опубликуйте oauth2-proxy на отдельном роутере по адресу oauth.example.com, так как браузер должен иметь доступ к /oauth2/sign_in и /oauth2/callback без прохождения проверки. Для этого отдельного хоста входа установите redirect_url в значение https://oauth.example.com/oauth2/callback и зарегистрируйте этот URI у провайдера.
При использовании конфигурации oauth2-proxy, приведенной выше, /oauth2/sign_in отображает страницу входа. Для автоматического перенаправления установите skip_provider_button = true в oauth2-proxy и добавьте statusRewrites: {"401": 302} в настройки errors в Traefik. Без этого перезаписывания Traefik возвращает автоматический редирект со статусом 401, и браузер не переходит по нему. Одно лишь перезаписывание не запускает процесс входа.
trustForwardHeader: true доверяет входящим заголовкам X-Forwarded-*; Traefik передает исходный хост и URI в oauth2-proxy. Эта опция считается устаревшей в текущей документации Traefik. Установите whitelist_domains, чтобы охватить этот хост, иначе oauth2-proxy отбросит параметр rd из-за риска open-redirect, и после входа все пользователи будут попадать на /. Сервер с Traefik обычно обслуживает несколько приложений одновременно, а в маршрутизации нескольких приложений Docker Compose через один экземпляр Traefik показана схема роутера, в которую встраивается данное решение.
Caddy: forward_auth
app.example.com {
handle /oauth2/* {
reverse_proxy 127.0.0.1:4180 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Uri {uri}
}
}
handle {
forward_auth 127.0.0.1:4180 {
uri /oauth2/auth
header_up X-Real-IP {remote_host}
copy_headers X-Auth-Request-User X-Auth-Request-Email
@error status 401
handle_response @error {
redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
}
}
reverse_proxy 127.0.0.1:3000
}
}Порядок следования имеет значение. Блок /oauth2/* должен идти первым и не содержать forward_auth, так как неавторизованный пользователь должен иметь доступ к путям входа и обратного вызова. Если разместить проверку перед этими путями, произойдет зацикливание перенаправлений на страницу входа, пока браузер не прервет соединение.
copy_headers передает данные об идентификации в вышестоящий запрос (upstream request). Этот механизм работает только при запуске oauth2-proxy с флагом set_xauthrequest = true. Выбор между различными прокси-серверами — отдельная задача, и сравнение Nginx, Caddy и Traefik поможет вам определиться.
Почему происходит зацикливание на странице входа?
Вы авторизуетесь у провайдера, он возвращает вас обратно, а oauth2-proxy снова перенаправляет на страницу входа. Зацикливание означает, что oauth2-proxy не принимает сессию при следующем запросе. Сессионная cookie может отсутствовать или не проходить проверку, например, если экземпляры используют разные cookie secrets. Откройте инструменты разработчика в браузере, найдите запрос к /oauth2/callback, который следует за редиректом от провайдера, и изучите заголовок ответа Set-Cookie. Если cookie установлена, но отсутствует в следующем запросе, значит, браузер её отклоняет. Если она присутствует, проверьте логи сервера на наличие ошибок валидации, таких как cookie signature not valid, и убедитесь, что все экземпляры используют одинаковый секрет.
Если пропадает CSRF-cookie, которую oauth2-proxy установил при отправке запроса, процесс не зацикливается. Он останавливается на этапе callback, а в логах указывается причина:
No cookies were found in OAuth callback.или, если другая cookie была получена, а нужная — нет:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF — это межсайтовая подделка запроса (cross-site request forgery), и эта cookie нужна, чтобы связать callback с инициированным входом. Браузер получает страницу с ошибкой 403 и текстом:
Login Failed: Unable to find a valid CSRF token. Please try again.Отсутствие cookie связано с тремя причинами, описанными ниже; еще одна причина ошибок валидации — рассинхронизация времени. Проверьте эти четыре пункта по порядку.
cookie_secure = trueпри обращении к сайту по обычному HTTP. За исключением localhost, браузер не сохранит cookie с флагомSecureдля источникаhttp://, поэтому она не будет отправлена обратно. Настройте TLS (transport layer security) должным образом или установитеcookie_secure = falseтолько для тестирования на localhost.- Значение
cookie_domainsне охватывает имя хоста в адресной строке..example.comохватываетapp.example.com, но никак не влияет наapp.example.net. - Браузер удаляет cookie. Строгие настройки приватности или расширения для блокировки сторонних cookie могут удалять
_oauth2_proxy_csrfмежду исходящим редиректом и callback, либо удалять сессионную cookie сразу после этого. - Рассинхронизация времени (clock drift). Если время на сервере значительно опережает время провайдера, ID-токен может выглядеть как просроченный и не пройти проверку.
timedatectlдолжен сообщать обSystem clock synchronized: yes.
Существует еще одна причина возникновения CSRF-ошибки при корректной конфигурации. По умолчанию oauth2-proxy хранит только одну CSRF-cookie, поэтому две вкладки, начавшие вход одновременно, перезаписывают данные друг друга. cookie_csrf_per_request = true позволяет каждой сессии входа иметь свою уникальную cookie.
Наблюдайте за процессом со стороны сервера, вместо того чтобы гадать:
sudo journalctl -u oauth2-proxy -fОткройте приложение в режиме инкогнито. Каждый запрос логируется вместе со своим статусом, поэтому callback, за которым сразу следует редирект на вход, — это и есть зафиксированное зацикливание.
Пути, которые должны пропускать авторизацию: API, вебхуки и вебсокеты
Forward auth предполагает наличие у браузера cookie. Клиенты без браузера не смогут пройти проверку.
API-клиент, отправляющий Authorization: Bearer <token>, не имеет cookie, поэтому приведенные выше конфигурации прокси перенаправляют его на страницу входа oauth2-proxy, если не включена аутентификация по bearer-токену. Есть два чистых решения. Параметр skip_jwt_bearer_tokens = true заставляет oauth2-proxy принимать валидный JWT (JSON web token) bearer-токен от настроенного издателя с аудиторией, принятой для этого клиента; это подходит, если ваши API-клиенты уже получают подходящие токены от провайдера. Поле aud токена должно совпадать с client_id или аудиторией, настроенной через extra_jwt_issuers. В противном случае исключите путь:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Каждое значение — это регулярное выражение, которое сопоставляется с декодированным путем без параметров запроса, опционально с префиксом HTTP-метода и =. POST=^/webhook/ оставляет приемник вебхука открытым для POST, в то время как пользователь, переходящий по тому же пути в браузере, все равно попадает на страницу входа, при условии, что запрос аутентификации сохраняет исходный метод. Nginx auth_request и Caddy forward_auth выполняют проверки GET, поэтому в таких конфигурациях исключения для конкретных методов требуют отдельной маршрутизации на уровне reverse proxy. Каждая запись — это брешь в защите, поэтому ограничивайте выражения с помощью ^ и делайте их максимально узкими, насколько это позволяет клиент.
Используйте версию v7.15.5 или новее, прежде чем полагаться на эти функции. В более ранних релизах после v7.5.0 можно было обойти защиту и исключить защищенный путь с помощью запроса, содержащего сегменты с точками, двойной ведущий слэш или точку с запятой (рекомендация GHSA-63jm-59jj-478j), и привязка выражений не предотвращала это. Исправленный релиз отказывается исключать такие неоднозначные пути, поэтому после обновления проверьте, что ваши публичные маршруты по-прежнему работают.
Вебсокеты — это случай, в котором часто ошибаются. Запрос на обновление (upgrade) — это обычный HTTP GET, содержащий те же cookie, что и любой другой запрос, поэтому он проходит проверку в обычном режиме и не требует исключения. Проблема возникает при проксировании. Без заголовков Upgrade и Connection в защищенной локации обновление никогда не завершается, и клиент приложения бесконечно повторяет попытки с сообщением WebSocket connection ... failed в консоли браузера. Исключение пути здесь ничего не исправит, так как запрос уже был авторизован.
Существует одно реальное ограничение. Проверка выполняется один раз, в момент обновления соединения. Вебсокет, который остается открытым часами, никогда не проверяется повторно, поэтому удаление пользователя у провайдера не закрывает уже установленное соединение. Чтобы прервать активные соединения, перезапустите приложение.
Хранение сессий и проблема чрезмерного размера cookie
По умолчанию вся сессия хранится внутри cookie, зашифрованного с помощью cookie_secret. Это позволяет oauth2-proxy оставаться stateless и не требует дополнительных сервисов. У этого подхода есть ограничение, так как браузеры ограничивают размер cookie примерно 4 KB. Когда ID token содержит длинный список групп (claims), oauth2-proxy разбивает сессию на части _oauth2_proxy_0, _oauth2_proxy_1 и последующие. При превышении определенного количества частей заголовки запроса становятся настолько большими, что nginx возвращает 400 Request Header Or Cookie Too Large еще до того, как приложение получит запрос.
В таких случаях перенесите хранение сессий на сторону сервера:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"В этом случае браузер хранит только короткий тикет, а зашифрованная сессия находится в Redis. Платой за это становится необходимость поддерживать работу дополнительного сервиса: если Redis недоступен, oauth2-proxy не может загрузить сессии, а потеря данных сессии вынуждает всех пользователей авторизоваться заново. У хранения в cookie есть свой недостаток: два запроса, одновременно обновляющие одну и ту же сессию, могут конфликтовать, что приведет к принудительному повторному входу.
Чего не дает forward auth
Это пропуск на входе. Он не является авторизацией внутри приложения, и эта разница определяет, подходит ли данный подход для вашей задачи.
Как только пользователь прошел проверку, приложение видит то же самое, что и всегда. Если у приложения есть собственные роли, forward auth не заполняет их, если только приложение не поддерживает аутентификацию на основе заголовков и не умеет сопоставлять заголовок с учетной записью. Grafana умеет это делать через настройки auth.proxy. Большинство self-hosted приложений — нет, поэтому для приложения каждый, кто прошел через «ворота», является одной и той же сущностью, и эта сущность часто обладает правами администратора.
Этот метод также не защищает собственные API-токены приложения. Персональный токен доступа, выданный приложением, проходит аутентификацию в приложении, а не в oauth2-proxy, поэтому токен перестает работать, как только перед ним оказывается «шлюз». Исключите путь API из проверки, чтобы вернуть его работоспособность, и этот токен станет единственным средством защиты пути. Теперь вы используете две системы аутентификации для одного сервиса, и SSO покрывает только одну из них.
Отзыв доступа — третий пробел. Удаление пользователя у вашего провайдера останавливает новые входы, но oauth2-proxy не проверяет существующую сессию у провайдера, пока не наступит время cookie_refresh. Если обновление (refresh) отключено, cookie сессии остается валидным до истечения срока действия, а cookie_expire по умолчанию составляет 168 часов, что может означать неделю доступа для того, кого вы только что удалили. Установите cookie_refresh на небольшое значение, например, один час. Когда провайдер отклоняет обновление, потому что refresh token пользователя больше не валиден, oauth2-proxy очищает сессию и принудительно вызывает повторный вход при следующем запросе, требующем обновления. Обновление поддерживается не всеми провайдерами, поэтому протестируйте его работу с вашим.
Аудиторский след также обрывается на «воротах». oauth2-proxy записывает, кто и когда прошел. Приложение записывает безымянную сессию. Если вам нужно ответить на вопрос, кто изменил настройку, идентификация через заголовки в приложении — это минимум, а реальные учетные записи для каждого пользователя — честный ответ.
Когда оплата SSO-тарифа — более верное решение
Forward auth является подходящим инструментом, если в приложении вообще нет системы входа или используется один общий пароль, а вам нужно централизованное место для добавления и удаления пользователей. Настройка занимает вторую половину дня и требует одного дополнительного процесса, при этом решение работает с любым приложением, поддерживающим HTTP.
Это неподходящий инструмент, если разным пользователям требуются разные права доступа внутри одного приложения. Прокси-шлюз не может выразить условие вида «Ана может редактировать дашборды, а Бо может только просматривать их». Если разработчик предлагает SSO-тариф, то вы, как правило, платите именно за возможность сопоставления групп с ролями; попытка реализовать это через заголовки и правила проксирования будет менее надежной, чем покупка официальной функции. Перед принятием решения стоит ознакомиться с моделью ценообразования для таких SSO-тарифов.
Любое приложение с мобильным или десктопным клиентом, который не использует браузерные cookies, будет конфликтовать со шлюзом при каждом запросе.
FAQ
Что такое forward auth?
Forward auth — это шаблон, при котором обратный прокси-сервер запрашивает у отдельного сервиса аутентификации разрешение для каждого входящего запроса перед тем, как передать его дальше. Прокси отправляет заголовки запроса на эндпоинт, такой как /oauth2/auth, и считывает код ответа. Код 202 означает разрешение, поэтому исходный запрос передается приложению. Код 401 означает отсутствие валидной сессии, поэтому прокси перенаправляет браузер на страницу входа. Nginx реализует это с помощью директивы auth_request, Traefik — через middleware forwardAuth, а Caddy — с помощью forward_auth.
Почему oauth2-proxy перенаправляет меня на страницу входа в бесконечном цикле?
Отсутствует cookie сессии или он не проходит проверку, поэтому каждая проверка обнаруживает отсутствие валидной сессии и возвращает вас на страницу входа. Экземпляры с разными cookie secrets отклоняют cookie друг друга. Другая причина — cookie_secure = true на сайте, к которому браузер обратился по обычному HTTP, так как, за исключением localhost, браузер не сохранит cookie с флагом Secure для источника http://. Также проверьте значение cookie_domains, которое может не охватывать имя хоста в адресной строке. Просмотрите заголовок Set-Cookie в ответе /oauth2/callback в инструментах разработчика браузера, чтобы увидеть, какой именно cookie теряется. Если cookie возвращается, проверьте лог сервера на наличие ошибок валидации. Если отсутствует CSRF-cookie, вы получите страницу 403 с текстом Login Failed: Unable to find a valid CSRF token. Please try again. вместо цикла, а в логе будет запись No cookies were found in OAuth callback., если cookie не были получены.
Как пропустить API-клиент или вебхук через oauth2-proxy?
Используйте skip_auth_routes с регулярным выражением, привязанным к началу строки, при необходимости ограничив его одним HTTP-методом (например, POST=^/webhook/), и используйте версию v7.15.5 или новее, в которой была исправлена критическая уязвимость обхода этих исключений. Исключения для конкретных методов требуют, чтобы запрос аутентификации сохранял исходный метод; примеры для Nginx и Caddy выполняют проверки через GET, поэтому обрабатывайте такие исключения в маршрутизации обратного прокси. Если ваши API-клиенты уже имеют валидные JWT, выданные настроенным провайдером с принятой аудиторией, skip_jwt_bearer_tokens = true примет эти токены вместо cookie и сохранит защиту пути. Аудитория должна соответствовать client_id или аудитории, настроенной через extra_jwt_issuers. Всё, что указано в skip_auth_routes, доступно без аутентификации для всех, поэтому делайте каждое выражение максимально узким, насколько это позволяет клиент.
Предоставляет ли oauth2-proxy приложению права доступа для конкретных пользователей?
Нет. Это шлюз, а не система авторизации. Он решает, кто получит доступ к приложению, и для приложения все пользователи выглядят одинаково, если только оно не считывает заголовки идентификации и не сопоставляет их с учетными записями. Grafana умеет это делать через настройки auth.proxy. Большинство self-hosted приложений не обладают такой функцией, поэтому каждый пользователь, прошедший через шлюз, использует ту же учетную запись, под которой запущено само приложение.
Может ли кто-то обойти oauth2-proxy, самостоятельно установив заголовок идентификации?
Да, если этот кто-то может обратиться к приложению напрямую. Идентификационные данные приходят в виде обычного заголовка, например X-Auth-Request-Email, и приложение доверяет всему, что получает. Любой, кто может установить соединение с портом приложения, может отправить этот заголовок и выдать себя за любого пользователя. Привязывайте приложение к 127.0.0.1 или держите его во внутренней сети Docker без опубликованных портов, подтверждая это с помощью sudo ss -tlnp.