oauth2-proxy: jak dodać SSO do aplikacji bez logowania
Dowiedz się jak wdrożyć mechanizm forward auth przy użyciu oauth2-proxy. Skonfiguruj Nginx lub Traefik, aby obsłużyć OIDC bez modyfikacji kodu źródłowego własnej aplikacji.
Forward auth: jak aplikacja bez logowania zyskuje SSO
oauth2-proxy zapewnia funkcjonalność single sign-on dla aplikacji, które nie posiadają własnego mechanizmu logowania. Działa to w ten sposób, że reverse proxy znajdujące się przed aplikacją wstrzymuje każde żądanie, pyta oauth2-proxy, czy żądanie zawiera poprawną sesję, i przekazuje je do backendu tylko wtedy, gdy odpowiedź jest twierdząca. Kod aplikacji pozostaje niezmieniony, ponieważ aplikacja nigdy nie widzi procesu weryfikacji.
Weryfikacja polega na wykonaniu jednego dodatkowego żądania HTTP. Proxy wysyła kopię nagłówków przychodzącego żądania do /oauth2/auth i odczytuje kod statusu. Kod 202 oznacza, że weryfikacja przebiegła pomyślnie, więc proxy przekazuje oryginalne żądanie do aplikacji. Kod 401 oznacza brak poprawnej sesji, więc proxy kieruje przeglądarkę do /oauth2/sign_in, która domyślnie wyświetla stronę logowania. /oauth2/start inicjuje logowanie OpenID Connect (OIDC) u dostawcy tożsamości; skip_provider_button = true sprawia, że /oauth2/sign_in uruchamia ten proces automatycznie. OIDC to warstwa tożsamości zbudowana w oparciu o OAuth 2.0, a dostawcą jest dowolne rozwiązanie używane już do obsługi logowań.
Ten wzorzec posiada własną nazwę w każdym reverse proxy. Nginx używa dyrektywy auth_request. Traefik nazywa to middleware forwardAuth. Caddy określa to jako forward_auth. Usługa odpowiadająca na podzapytania jest również wymienna. oauth2-proxy jest powszechnym wyborem, ponieważ obsługuje standard OIDC i nie wymaga własnej bazy danych.
Wyznacz granicę zaufania przed przystąpieniem do konfiguracji
Po pomyślnej weryfikacji oauth2-proxy zwraca tożsamość w nagłówkach odpowiedzi, a reverse proxy kopiuje je do żądania kierowanego do backendu. Przy włączonym set_xauthrequest otrzymuje się X-Auth-Request-User oraz X-Auth-Request-Email. Aplikacja odczytuje te nagłówki i uznaje je za wiarygodne.
To cały model bezpieczeństwa, dlatego należy jasno określić jego konsekwencje. Każdy podmiot, który może nawiązać połączenie TCP z portem aplikacji, może samodzielnie ustawić te nagłówki i podszyć się pod dowolnego użytkownika. Pojedynczy curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/ stanowi całkowite obejście zabezpieczeń, jeśli żądanie trafi bezpośrednio do aplikacji.
Zatem aplikacja nie może być dostępna w żaden inny sposób niż przez proxy. W Docker Compose należy usunąć mapowanie ports: z usługi aplikacji i pozostawić ją w sieci wewnętrznej, aby tylko kontener proxy mógł się z nią połączyć. Na serwerze typu bare metal należy powiązać aplikację z adresem 127.0.0.1:3000 zamiast 0.0.0.0:3000. Następnie należy sprawdzić, co faktycznie zostało wystawione:
sudo ss -tlnp | grep 3000Wiersz zawierający 0.0.0.0:3000 oznacza, że aplikacja odpowiada na publicznym adresie IP, a brama jest jedynie dekoracją. 127.0.0.1:3000 to pożądany stan. Reguła firewalla stanowi przydatną drugą warstwę ochrony, jednak adres powiązania jest tym elementem, który pozostaje skuteczny nawet po wyczyszczeniu zestawu reguł przez inne narzędzie.
Instalacja oauth2-proxy
Według stanu na październik 2026 r. aktualnym wydaniem jest v7.15.5, opublikowane 1 października 2026 r. Usuwa ono dwie krytyczne luki bezpieczeństwa, z których jedna dotyczy obejścia skip_auth_routes i występuje w każdym wydaniu po v7.5.0, dlatego nie należy instalować starszych wersji. Zainstaluj plik binarny i zweryfikuj pobrany plik:
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 musi wyświetlić linię kończącą się ciągiem OK. Jeśli wyświetli FAILED, przerwij proces i pobierz plik ponownie, zamiast uruchamiać plik binarny.
W środowisku Docker obrazem jest quay.io/oauth2-proxy/oauth2-proxy i należy przypiąć wersję tagiem: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Pozostawienie tagu latest zmienia rutynowe polecenie docker compose pull w nieplanowaną aktualizację procesu zabezpieczającego wszystkie aplikacje na serwerze.
Generowanie klucza tajnego ciasteczka
Ciasteczko sesyjne jest szyfrowane, a cookie_secret stanowi klucz. Klucz szyfrujący musi mieć dokładnie 16, 24 lub 32 bajty, ponieważ staje się on kluczem AES (Advanced Encryption Standard). oauth2-proxy akceptuje wartość base64 bezpieczną dla adresów URL, która po zdekodowaniu ma jedną z tych długości, lub surowy klucz o takiej długości; w przeciwnym razie usługa odmawia uruchomienia, zgłaszając błąd startu wskazujący na klucz tajny ciasteczka. Poniższe polecenie generuje 44-znakową wartość kodującą 32-bajtowy klucz.
openssl rand -base64 32 | tr -- '+/' '-_'Ciąg tr nie jest opcjonalny. Konwertuje on standardowe base64 na alfabet bezpieczny dla adresów URL, którego oauth2-proxy używa podczas dekodowania klucza.
Obowiązują dwie zasady dotyczące tej wartości. Należy używać osobnego klucza dla każdego wdrożenia. W przypadku uruchamiania więcej niż jednej instancji oauth2-proxy w ramach tej samej domeny, należy nadać im wszystkim ten sam klucz, ponieważ ciasteczko zaszyfrowane przez jedną instancję musi być możliwe do odczytania przez pozostałe.
Konfiguracja oauth2-proxy
Przechowywanie ustawień w pliku, zamiast w długiej linii poleceń, zapobiega wyświetlaniu client secret w danych wyjściowych 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 instruuje oauth2-proxy, aby ufało nagłówkom X-Forwarded-* pochodzącym z poprzedzającego go proxy. Bez tego ustawienia oauth2-proxy traktuje adres proxy jako adres klienta, co może prowadzić do błędnej oceny, czy żądanie dotarło przez HTTPS.
trusted_proxy_ips ogranicza listę hostów, które mogą przesyłać te nagłówki. Domyślna konfiguracja ufa każdemu źródłu, co jest bezpieczne tylko dlatego, że http_address utrzymuje oauth2-proxy na 127.0.0.1. Jeśli oauth2-proxy działa w sieci Docker, należy ustawić tę wartość na adres reverse proxy.
upstreams = ["static://202"] sprawia, że oauth2-proxy odpowiada kodem 202 na uwierzytelnione żądanie i nie przekazuje ruchu dalej, co jest wymagane w modelu forward auth, ponieważ to reverse proxy zajmuje się przekazywaniem żądań. Alternatywny model wdrażania umieszcza oauth2-proxy bezpośrednio w ścieżce żądania za pomocą upstreams = ["http://127.0.0.1:3000"] i bez użycia auth_request. Jest to prostsze rozwiązanie dla jednej aplikacji, ale nie skaluje się przy większej ich liczbie.
email_domains = ["*"] dopuszcza każdy adres, który zostanie uwierzytelniony przez dostawcę. Warto ograniczyć to ustawienie do własnej domeny lub, co jest lepszym rozwiązaniem, kontrolować dostęp poprzez przypisanie do grup u dostawcy, gdyż to tam zarządzane są konta użytkowników.
Uruchom usługę przez systemd na dedykowanym koncie użytkownika:
# /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 wyświetlające OK oznacza, że proces został uruchomiony i wczytał konfigurację. Jest to wbudowany punkt kontroli stanu (health endpoint) oauth2-proxy, który nie wymaga sesji. Jeśli brak odpowiedzi, sprawdź journalctl -u oauth2-proxy -n 50, ponieważ błędny adres URL wystawcy lub nieprawidłowa długość cookie secret powodują błąd przy starcie, o czym informują logi.
Rejestracja URI przekierowania u dostawcy
Utwórz aplikację OIDC u swojego dostawcy i ustaw jej URI przekierowania dokładnie na redirect_url z konfiguracji: https://app.example.com/oauth2/callback. Dokładnie oznacza, że schemat, host, port oraz ścieżka muszą zgadzać się znak w znak. Końcowy ukośnik sprawia, że jest to inny URI.
Jest to najczęstsza przyczyna niepowodzeń w całej konfiguracji, a błąd występuje, zanim oauth2-proxy w ogóle zacznie działać. Dostawca odrzuca żądanie autoryzacji i wyświetla własną stronę błędu, więc w dzienniku oauth2-proxy nie pojawia się żaden wpis. Wskazówką jest pasek adresu: przeglądarka nadal znajduje się w domenie dostawcy, a ciąg zapytania zawiera error=invalid_request lub bezpośrednio nazwy stron redirect_uri. W takiej sytuacji należy poprawić rekord aplikacji u dostawcy, a nie konfigurację proxy.
Skopiuj adres URL wystawcy (issuer URL) od dostawcy zamiast wpisywać go ręcznie. oauth2-proxy dodaje /.well-known/openid-configuration do oidc_issuer_url i pobiera ten dokument wykrywania (discovery document) podczas uruchamiania. Sprawdź go najpierw samodzielnie:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400JSON zawierający klucz authorization_endpoint jest pierwszym punktem weryfikacji; wartość issuer w dokumencie musi również dokładnie zgadzać się z oidc_issuer_url. Błąd 404 lub strona błędu w formacie HTML oznacza, że adres jest nieprawidłowy, a oauth2-proxy nie uruchomi się z powodu tego samego błędu 404. Jeśli jeszcze nie wybrano dostawcy, porównanie Keycloak, Authentik i Zitadel omawia wady i zalety tych rozwiązań, a uruchomienie Authentik jako własnego serwera SSO przeprowadza przez konfigurację strony dostawcy w tym konkretnym scenariuszu.
Nginx: auth_request
Nginx realizuje uwierzytelnianie przekazywane za pomocą auth_request, który wyzwala wewnętrzne podzapytanie i podejmuje decyzję w oparciu o jego kod statusu.
# 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;
}
}Trzy szczegóły w tym rozwiązaniu mają kluczowe znaczenie. proxy_pass_request_body off z pustym Content-Length zapobiega przesyłaniu przez Nginx treści żądania do punktu końcowego uwierzytelniania, który wymaga jedynie nagłówków.
Para auth_request_set $auth_cookie oraz add_header Set-Cookie przekazuje odświeżony plik cookie sesji z powrotem do przeglądarki. Bez tego elementu cookie_refresh nie podejmuje żadnego działania, ponieważ Nginx odrzuca nagłówki Set-Cookie z podzapytania, a przeglądarka zachowuje starą wartość do momentu wygaśnięcia sesji. Ta para obsługuje jeden plik cookie; dzielone pliki cookie sesji wymagają dodatkowej obsługi pozostałych części lub wykorzystania pamięci sesji Redis.
error_page 401 = @oauth2_signin to dyrektywa, która przekształca nieudane sprawdzenie w proces logowania. Bez niej nieuwierzytelniony użytkownik otrzymuje jedynie surową stronę 401 Authorization Required i nie ma możliwości kontynuowania pracy.
Zawsze wykonuj test przed przeładowaniem konfiguracji:
sudo nginx -t && sudo systemctl reload nginxJeśli otaczające dyrektywy są nowe, anatomia konfiguracji reverse proxy w nginx opisuje warstwę znajdującą się poniżej.
Traefik: middleware forwardAuth
Traefik wymaga dwóch middleware do wykonania tego zadania. Pierwszy przeprowadza weryfikację. Drugi wyświetla stronę logowania, gdy weryfikacja kończy się niepowodzeniem.
# 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}"Podepnij oba do routera obsługującego aplikację, umieszczając oauth-errors przed oauth-auth, a oauth2-proxy opublikuj na osobnym routerze pod adresem oauth.example.com. Przeglądarka musi mieć możliwość połączenia z /oauth2/sign_in oraz /oauth2/callback bez przechodzenia przez weryfikację. Dla tego osobnego hosta logowania ustaw redirect_url na https://oauth.example.com/oauth2/callback i zarejestruj ten URI u dostawcy tożsamości.
Przy powyższej konfiguracji oauth2-proxy, /oauth2/sign_in renderuje stronę logowania. Aby uzyskać automatyczne przekierowanie, ustaw skip_provider_button = true w oauth2-proxy i dodaj statusRewrites: {"401": 302} w ustawieniach errors w Traefik. Bez tego nadpisania (rewrite), Traefik zwraca automatyczne przekierowanie ze statusem 401, a przeglądarka go nie wykonuje. Samo nadpisanie nie inicjuje procesu logowania.
trustForwardHeader: true ufa przychodzącym nagłówkom X-Forwarded-*; Traefik przekazuje oryginalny host oraz URI do oauth2-proxy. Ta opcja jest uznana za przestarzałą w aktualnej dokumentacji Traefik. Ustaw whitelist_domains tak, aby obejmowała również ten host, w przeciwnym razie oauth2-proxy odrzuci parametr rd jako ryzyko typu open-redirect, co spowoduje, że po zalogowaniu użytkownicy będą trafiać na /. Instancja Traefik zazwyczaj obsługuje kilka aplikacji jednocześnie, a kierowanie ruchu do kilku aplikacji Docker Compose przez jedną instancję Traefik przedstawia układ routerów, w który wpisuje się to rozwiązanie.
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
}
}Kolejność ma tutaj znaczenie. Blok /oauth2/* musi znajdować się na początku i nie zawierać forward_auth, ponieważ niezalogowany użytkownik musi mieć możliwość dotarcia do ścieżek logowania oraz callback. Umieszczenie weryfikacji przed tymi ścieżkami spowoduje, że proces logowania będzie przekierowywał w nieskończoność, aż przeglądarka przerwie połączenie.
copy_headers odpowiada za przekazanie tożsamości do żądania upstream i generuje wartości tylko wtedy, gdy oauth2-proxy działa z flagą set_xauthrequest = true. Wybór odpowiedniego proxy jest osobnym zagadnieniem, które omawia porównanie Nginx, Caddy i Traefik.
Dlaczego logowanie zapętla się i wraca do strony logowania?
Użytkownik loguje się u dostawcy, zostaje odesłany z powrotem, a oauth2-proxy ponownie przekierowuje go do strony logowania. Pętla oznacza, że oauth2-proxy nie akceptuje poprawnej sesji przy kolejnym żądaniu. Ciasteczko sesji może być nieobecne lub może być obecne, ale nie przechodzić walidacji, na przykład gdy instancje używają różnych wartości cookie secrets. Otwórz narzędzia deweloperskie w przeglądarce, znajdź żądanie do /oauth2/callback, które następuje po przekierowaniu od dostawcy, i odczytaj nagłówek odpowiedzi Set-Cookie. Ciasteczko, które jest tam ustawiane, a którego brakuje w kolejnym żądaniu, jest tym, które przeglądarka odrzuca. Jeśli ciasteczko jest obecne, sprawdź dziennik serwera pod kątem błędów walidacji, takich jak cookie signature not valid, i potwierdź, że wszystkie instancje używają tego samego secret.
Gdy brakującym ciasteczkiem jest ciasteczko CSRF ustawione przez oauth2-proxy przy wychodzącym żądaniu, proces nie zapętla się. Zatrzymuje się na callback, a dziennik wskazuje przyczynę:
No cookies were found in OAuth callback.lub, gdy inne ciasteczko dotarło, ale właściwe nie:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF to cross-site request forgery; ciasteczko to istnieje, aby callback mógł zostać powiązany z logowaniem, które go zainicjowało. Przeglądarka otrzymuje stronę z błędem 403 zawierającą:
Login Failed: Unable to find a valid CSRF token. Please try again.Brakujące ciasteczka wynikają z trzech poniższych przyczyn; inną przyczyną błędów walidacji jest rozbieżność czasu (clock drift). Sprawdź te cztery punkty w podanej kolejności.
cookie_secure = truepodczas gdy przeglądarka uzyskała dostęp do witryny przez zwykłe HTTP. Poza localhost, przeglądarka nie zapisze ciasteczka oznaczonegoSecuredla źródłahttp://, więc nigdy nie zostanie ono odesłane. Zakończ TLS (transport layer security) poprawnie lub ustawcookie_secure = falsetylko podczas testów na localhost.- Wartość
cookie_domains, która nie obejmuje nazwy hosta w pasku adresu..example.comobejmujeapp.example.comi nie ma żadnego wpływu naapp.example.net. - Przeglądarka odrzuca ciasteczko. Restrykcyjne rozszerzenie chroniące prywatność lub blokowanie ciasteczek stron trzecich może usunąć
_oauth2_proxy_csrfmiędzy wychodzącym przekierowaniem a callback, lub ciasteczko sesji po nim. - Rozbieżność czasu (clock drift). Jeśli zegar serwera znacznie wyprzedza zegar dostawcy, token ID może wydawać się wygasły i nie przejść walidacji.
timedatectlpowinno zgłosićSystem clock synchronized: yes.
Jeszcze jedna przyczyna powoduje błąd CSRF bez błędnej konfiguracji. Domyślnie oauth2-proxy utrzymuje pojedyncze ciasteczko CSRF, więc dwa logowania rozpoczęte w tym samym momencie w różnych kartach nadpisują się nawzajem. cookie_csrf_per_request = true nadaje każdemu logowaniu własne ciasteczko.
Obserwuj proces po stronie serwera zamiast zgadywać:
sudo journalctl -u oauth2-proxy -fZaładuj aplikację w oknie prywatnym. Każde żądanie jest rejestrowane wraz ze statusem, więc callback, po którym natychmiast następuje kolejne przekierowanie do logowania, jest zarejestrowaną pętlą.
Ścieżki, które muszą pomijać logowanie: API, webhooks i websockets
Forward auth zakłada, że przeglądarka przechowuje ciasteczko. Klienci bez przeglądarki nie przejdą tego procesu.
Klient API wysyłający Authorization: Bearer <token> nie posiada ciasteczka, więc powyższe konfiguracje proxy przekierują go na stronę logowania oauth2-proxy, chyba że włączono uwierzytelnianie bearer-token. Istnieją dwa poprawne rozwiązania. Ustawienie skip_jwt_bearer_tokens = true sprawia, że oauth2-proxy akceptuje poprawny token JWT (JSON web token) od skonfigurowanego wystawcy, z grupą odbiorców (audience) zaakceptowaną dla tego klienta. Jest to właściwe podejście, gdy klienci API otrzymują odpowiednie tokeny od dostawcy. Pole aud tokena musi być zgodne z client_id lub grupą odbiorców skonfigurowaną przez extra_jwt_issuers. W przeciwnym razie należy wykluczyć ścieżkę:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Każda wartość jest wyrażeniem regularnym dopasowywanym do zdekodowanej ścieżki bez parametrów zapytania, opcjonalnie poprzedzonym metodą HTTP i =. POST=^/webhook/ pozostawia odbiornik webhook otwarty dla metody POST, podczas gdy użytkownik przeglądający tę samą ścieżkę nadal trafia na stronę logowania, pod warunkiem, że żądanie uwierzytelnienia zachowuje oryginalną metodę. Nginx auth_request oraz Caddy forward_auth wykonują sprawdzenia metodą GET, więc w tych konfiguracjach wykluczenia specyficzne dla metody wymagają osobnego routingu na poziomie reverse proxy. Każdy wpis stanowi lukę w zabezpieczeniach, dlatego należy ograniczyć wyrażenia za pomocą ^ i zachować ich możliwie najwęższy zakres, na jaki pozwala klient.
Przed skorzystaniem z tych funkcji należy użyć wersji v7.15.5 lub nowszej. Wcześniejsze wydania po v7.5.0 mogły zostać oszukane w celu wykluczenia chronionej ścieżki za pomocą żądania zawierającego segmenty z kropkami, podwójny ukośnik na początku lub średnik (biuletyn GHSA-63jm-59jj-478j), a kotwiczenie wyrażeń nie zapobiegało temu problemowi. Poprawione wydanie odrzuca takie niejednoznaczne ścieżki, więc po aktualizacji należy sprawdzić, czy publiczne trasy nadal działają poprawnie.
Websockets to przypadek, w którym często popełniane są błędy. Żądanie upgrade jest zwykłym żądaniem HTTP GET, przenoszącym te same ciasteczka co każde inne żądanie, więc przechodzi ono weryfikację standardowo i nie wymaga wykluczenia. Problemem jest konfiguracja proxy wokół tego procesu. Bez nagłówków Upgrade oraz Connection w chronionej lokalizacji, proces upgrade nigdy nie zostanie zakończony, a klient aplikacji będzie ponawiał próby w nieskończoność, wyświetlając komunikat WebSocket connection ... failed w konsoli przeglądarki. Wykluczenie ścieżki w tym przypadku nic nie daje, ponieważ żądanie zostało już autoryzowane.
Obowiązuje jedno realne ograniczenie. Weryfikacja odbywa się jednorazowo, w momencie upgrade. Websocket, który pozostaje otwarty przez wiele godzin, nie jest ponownie sprawdzany, więc usunięcie użytkownika u dostawcy nie zamknie aktywnego połączenia. Aby przerwać aktywne sesje, należy zrestartować aplikację.
Przechowywanie sesji i problem zbyt dużego pliku cookie
Domyślnie cała sesja jest przechowywana wewnątrz pliku cookie, zaszyfrowana za pomocą cookie_secret. Dzięki temu oauth2-proxy pozostaje bezstanowe i nie wymaga dodatkowej usługi. Rozwiązanie to posiada jednak ograniczenie, ponieważ przeglądarki nakładają limit wielkości pliku cookie wynoszący około 4 KB. Gdy token ID zawiera długą listę oświadczeń o grupach (group claims), oauth2-proxy dzieli sesję na części _oauth2_proxy_0, _oauth2_proxy_1 i kolejne. Po przekroczeniu kilku części nagłówki żądania stają się na tyle duże, że nginx zwraca błąd 400 Request Header Or Cookie Too Large, zanim aplikacja otrzyma żądanie.
W takiej sytuacji należy przenieść przechowywanie sesji po stronie serwera:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"Przeglądarka przechowuje wówczas jedynie krótki bilet (ticket), a zaszyfrowana sesja znajduje się w Redis. Kosztem tego rozwiązania jest konieczność utrzymania dodatkowej usługi: jeśli Redis przestanie działać, oauth2-proxy nie będzie w stanie wczytać sesji. Utrata zapisanych danych sesji wymusi na wszystkich użytkownikach ponowne logowanie. Magazyn oparty na plikach cookie ma swoje własne wady: dwa żądania odświeżające tę samą sesję w tym samym momencie mogą wywołać konflikt i wymusić ponowne logowanie.
Czego nie zapewnia forward auth
Jest to mechanizm kontroli dostępu na poziomie bramy. Nie stanowi on autoryzacji wewnątrz aplikacji, a ta różnica decyduje o tym, czy dane podejście jest odpowiednie dla danego przypadku.
Gdy użytkownik przejdzie przez bramę, aplikacja widzi to, co widziała zawsze. Jeśli aplikacja posiada własne role, forward auth ich nie uzupełnia, chyba że aplikacja obsługuje uwierzytelnianie oparte na nagłówkach i mapuje nagłówek na konto. Grafana to umożliwia poprzez ustawienia auth.proxy. Większość aplikacji self-hosted tego nie robi, więc każda osoba, która przejdzie przez bramę, jest dla aplikacji tą samą tożsamością, często z uprawnieniami administratora.
Mechanizm ten nie chroni również własnych tokenów API aplikacji. Osobisty token dostępu (personal access token) wydany przez aplikację uwierzytelnia użytkownika w aplikacji, a nie w oauth2-proxy, więc token przestaje działać w momencie, gdy przed aplikacją stanie brama. Wyłączenie ścieżki API spod ochrony przywraca działanie tokena, ale staje się on jedynym zabezpieczeniem tej ścieżki. W efekcie w ramach jednej usługi działają dwa systemy uwierzytelniania, z których tylko jeden jest objęty SSO.
Trzecią luką jest unieważnianie sesji. Usunięcie użytkownika u dostawcy tożsamości blokuje nowe logowania, ale oauth2-proxy nie sprawdza istniejącej sesji u dostawcy, dopóki nie nadejdzie czas cookie_refresh. Przy wyłączonym odświeżaniu, ciasteczko sesji pozostaje ważne aż do wygaśnięcia, a wartość domyślna cookie_expire wynosi 168 godzin, co może oznaczać tydzień dostępu dla osoby, której uprawnienia właśnie odebrano. Należy ustawić cookie_refresh na krótką wartość, na przykład jedną godzinę. Gdy dostawca odrzuci odświeżenie, ponieważ token odświeżania użytkownika nie jest już ważny, oauth2-proxy usuwa sesję i wymusza ponowne logowanie przy kolejnym żądaniu wymagającym odświeżenia. Odświeżanie nie jest obsługiwane przez każdego dostawcę, dlatego należy przetestować tę funkcję w swoim środowisku.
Ścieżka audytu również kończy się na bramie. oauth2-proxy rejestruje, kto i kiedy przeszedł przez bramę. Aplikacja rejestruje sesję bez przypisanej tożsamości. Jeśli konieczne jest ustalenie, kto zmienił ustawienia, minimalnym rozwiązaniem jest przekazywanie tożsamości w nagłówkach, natomiast rzetelnym rozwiązaniem są indywidualne konta użytkowników wewnątrz aplikacji.
Kiedy opłacenie subskrypcji SSO jest lepszym rozwiązaniem
Forward auth jest właściwym narzędziem, gdy aplikacja nie posiada mechanizmu logowania lub korzysta z jednego współdzielonego hasła, a wymagane jest centralne zarządzanie dostępem użytkowników. Implementacja zajmuje jedno popołudnie, wymaga uruchomienia dodatkowego procesu i działa z każdą aplikacją obsługującą protokół HTTP.
Jest to niewłaściwe narzędzie, gdy różni użytkownicy wymagają różnych uprawnień wewnątrz tej samej aplikacji. Mechanizm bramy nie pozwala na zdefiniowanie reguł typu „Ana może edytować pulpity, a Bo może je tylko przeglądać”. Jeśli dostawca oferuje wersję aplikacji z obsługą SSO, zazwyczaj płaci się za mapowanie grup na role. Próba odtworzenia tej funkcjonalności za pomocą nagłówków i reguł proxy jest bardziej podatna na awarie niż wykupienie subskrypcji. Warto zapoznać się z artykułem Model cenowy stojący za poziomami SSO przed podjęciem decyzji.
Każda aplikacja z klientem mobilnym lub desktopowym, który nie obsługuje plików cookie przeglądarki, będzie powodować konflikty z bramą przy każdym żądaniu.
FAQ
Czym jest forward auth?
Forward auth to wzorzec, w którym reverse proxy przed przekazaniem żądania do backendu pyta zewnętrzną usługę uwierzytelniającą o uprawnienia. Proxy przesyła nagłówki żądania do punktu końcowego, takiego jak /oauth2/auth, i odczytuje kod statusu. Kod 202 oznacza dostęp dozwolony, więc oryginalne żądanie jest przekazywane do aplikacji. Kod 401 oznacza brak ważnej sesji, co powoduje przekierowanie przeglądarki do strony logowania. Nginx implementuje ten mechanizm za pomocą dyrektywy auth_request, Traefik poprzez middleware forwardAuth, a Caddy przy użyciu forward_auth.
Dlaczego oauth2-proxy zapętla przekierowania do strony logowania?
Przyczyną jest brak lub niepoprawna walidacja ciasteczka sesji, przez co każda weryfikacja kończy się niepowodzeniem i ponownym przekierowaniem. Instancje używające różnych sekretów ciasteczek (cookie secrets) odrzucają swoje ciasteczka nawzajem. Inna przyczyna to cookie_secure = true w witrynie dostępnej przez zwykłe HTTP, ponieważ poza localhost przeglądarka nie zapisze ciasteczka Secure dla źródła http://. Należy również sprawdzić, czy wartość cookie_domains obejmuje nazwę hosta widoczną w pasku adresu. W narzędziach deweloperskich przeglądarki należy sprawdzić nagłówek Set-Cookie w odpowiedzi /oauth2/callback, aby ustalić, które ciasteczko nie jest przesyłane. Jeśli ciasteczko jest zwracane, należy sprawdzić dziennik serwera pod kątem błędów walidacji. W przypadku braku ciasteczka CSRF zamiast pętli występuje błąd 403 z komunikatem Login Failed: Unable to find a valid CSRF token. Please try again., a w dzienniku pojawia się wpis No cookies were found in OAuth callback., gdy nie dotarły żadne ciasteczka.
Jak przepuścić klienta API lub webhook przez oauth2-proxy?
Należy użyć skip_auth_routes z wyrażeniem regularnym, opcjonalnie ograniczonym do jednej metody HTTP, na przykład POST=^/webhook/, oraz korzystać z wersji v7.15.5 lub nowszej, w której naprawiono krytyczne obejście tych wykluczeń. Wykluczenia specyficzne dla metody wymagają, aby żądanie uwierzytelniające zachowało oryginalną metodę; przykłady dla Nginx i Caddy wykonują sprawdzenia GET, więc wykluczenia te należy obsłużyć w routingu reverse proxy. Jeśli klienci API posiadają już ważne tokeny JWT wydane przez skonfigurowanego dostawcę z akceptowaną grupą odbiorców (audience), skip_jwt_bearer_tokens = true zaakceptuje te tokeny zamiast ciasteczka, utrzymując ochronę ścieżki. Grupa odbiorców musi być zgodna z client_id lub z grupą skonfigurowaną przez extra_jwt_issuers. Wszystko wymienione w skip_auth_routes jest nieuwierzytelnione dla każdego użytkownika, dlatego każde wyrażenie powinno być tak wąskie, jak pozwala na to klient.
Czy oauth2-proxy nadaje aplikacji uprawnienia per-użytkownik?
Nie. Jest to brama, a nie system autoryzacji. Decyduje ona jedynie o tym, kto uzyska dostęp do aplikacji. Każdy użytkownik, który przejdzie przez bramę, jest dla aplikacji identyczny, chyba że aplikacja odczytuje nagłówki tożsamości i mapuje je na konta. Grafana umożliwia to poprzez ustawienia auth.proxy. Większość aplikacji self-hosted nie posiada takiej funkcji, więc każda osoba za bramą współdzieli tożsamość, z którą uruchomiona jest aplikacja.
Czy można obejść oauth2-proxy poprzez samodzielne ustawienie nagłówka tożsamości?
Tak, jeśli istnieje możliwość bezpośredniego połączenia z aplikacją. Tożsamość jest przesyłana jako zwykły nagłówek, taki jak X-Auth-Request-Email, a aplikacja ufa wszystkiemu, co otrzyma. Każdy, kto może otworzyć połączenie z portem aplikacji, może wysłać ten nagłówek i podszyć się pod dowolnego użytkownika. Należy powiązać aplikację z 127.0.0.1 lub umieścić ją w wewnętrznej sieci Docker bez wystawionego portu, co można potwierdzić za pomocą sudo ss -tlnp.