Her Uygulamaya oauth2-proxy ile SSO Eklemek
Giriş özelliği olmayan uygulamaları OIDC ile koruyun. oauth2-proxy'yi nginx veya Traefik'e bağlayın; /oauth2/auth, 202, çerez ve yönlendirme tuzaklarını öğrenin.
Forward auth: giriş özelliği olmayan bir uygulamaya SSO kazandırma
oauth2-proxy, kendi giriş mekanizması bulunmayan bir uygulamaya tek oturum açma (SSO) özelliği kazandırır. Bu yöntem, uygulamanın önündeki reverse proxy'nin her isteği durdurması, oauth2-proxy'ye isteğin geçerli bir oturum taşıyıp taşımadığını sorması ve yalnızca yanıt olumlu olduğunda isteği yukarı yöne (upstream) iletmesi prensibiyle çalışır. Uygulama kodu hiçbir değişikliğe uğramaz çünkü uygulama bu denetimden haberdar olmaz.
Denetim işlemi, fazladan bir HTTP isteğinden ibarettir. Proxy, gelen istek başlıklarının bir kopyasını /oauth2/auth adresine gönderir ve dönen durum kodunu okur. 202 kodu denetimin başarılı olduğunu gösterir; bu durumda proxy, orijinal isteği uygulamaya iletir. 401 kodu geçerli bir oturum olmadığını belirtir; bu durumda proxy, tarayıcıyı varsayılan olarak bir giriş sayfası görüntüleyen /oauth2/sign_in adresine yönlendirir. /oauth2/start, kimlik sağlayıcınızda bir OpenID Connect (OIDC) giriş süreci başlatır; skip_provider_button = true ise /oauth2/sign_in üzerinde bu sürecin otomatik olarak başlamasını sağlar. OIDC, OAuth 2.0 üzerine inşa edilmiş kimlik katmanıdır ve sağlayıcı, giriş işlemleri için halihazırda kullandığınız herhangi bir servistir.
Bu modelin her reverse proxy yazılımında bir karşılığı vardır. Nginx bu direktife auth_request adını verir. Traefik, bu ara katmanı (middleware) forwardAuth olarak adlandırır. Caddy ise bunu forward_auth şeklinde tanımlar. Alt isteği yanıtlayan servis de değiştirilebilir niteliktedir. oauth2-proxy, standart OIDC protokolünü desteklediği ve kendi veritabanına ihtiyaç duymadığı için yaygın olarak tercih edilir.
Yapılandırmayı yazmadan önce güven sınırını belirleyin
Başarılı bir kontrolden sonra oauth2-proxy, kimlik bilgilerini yanıt başlıkları (response headers) olarak döndürür ve reverse proxy bunları upstream isteğine kopyalar. set_xauthrequest etkinleştirildiğinde X-Auth-Request-User ve X-Auth-Request-Email elde edersiniz. Uygulama bu başlıkları okur ve onlara güvenir.
Tüm güvenlik modeli bundan ibarettir, bu yüzden sonucunu açıkça ifade edin. Uygulama portuna TCP bağlantısı açabilen herhangi bir şey, bu başlıkları kendisi ayarlayabilir ve herhangi bir kullanıcı kimliğine bürünebilir. Tek bir curl -H "X-Auth-Request-Email: admin@example.com" http://127.0.0.1:3000/, uygulamaya doğrudan ulaşırsa tam bir güvenlik atlatmasıdır.
Bu nedenle uygulama, proxy dışında hiçbir yolla erişilebilir olmamalıdır. Docker Compose içinde, uygulama servisinden ports: eşlemesini kaldırın ve onu sadece proxy container'ının erişebileceği dahili ağda bırakın. Çıplak bir sunucuda (bare host), uygulamayı 0.0.0.0:3000 yerine 127.0.0.1:3000 adresine bağlayın. Ardından gerçekte neyi dışarıya açtığınızı kontrol edin:
sudo ss -tlnp | grep 30000.0.0.0:3000 yazan bir satır, uygulamanın genel IP adresi üzerinden yanıt verdiğini ve geçidinizin sadece dekoratif olduğunu gösterir. İstediğiniz sonuç 127.0.0.1:3000 olmalıdır. Bir güvenlik duvarı kuralı faydalı bir ikinci katmandır, ancak bağlama adresi (bind address), kurallar kümenizi temizleyen başka bir araçtan etkilenmeden varlığını sürdüren tek yöntemdir.
oauth2-proxy kurulumu
Ekim 2026 itibarıyla güncel sürüm, 1 Ekim 2026 tarihinde yayınlanan v7.15.5 sürümüdür. Bu sürüm, v7.5.0 sonrası tüm sürümleri etkileyen ve skip_auth_routes atlatma zafiyeti de dahil olmak üzere iki kritik güvenlik açığını gidermektedir; bu nedenle daha eski bir sürüm kurmayın. İkili dosyayı kurun ve indirme işlemini doğrulayın:
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 ile biten bir satır çıktısı vermelidir. Eğer FAILED çıktısını alırsanız, işlemi durdurun ve ikili dosyayı çalıştırmak yerine yeniden indirin.
Docker ortamında imaj quay.io/oauth2-proxy/oauth2-proxy şeklindedir ve etiket sabitlemesi yapmalısınız: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5. Etiketi latest olarak bırakmak, rutin bir docker compose pull işlemini, sunucudaki her uygulamayı koruyan tek sürecin plansız bir şekilde yükseltilmesine dönüştürür.
Cookie secret değerini oluşturma
Oturum çerezi şifrelenmiştir ve cookie_secret bu işlem için kullanılan anahtardır. Şifreleme anahtarı, bir AES (Advanced Encryption Standard) anahtarına dönüştüğü için tam olarak 16, 24 veya 32 bayt uzunluğunda olmalıdır. oauth2-proxy, bu uzunluklardan birine karşılık gelen URL güvenli bir base64 değeri veya ham bir gizli anahtar kabul eder; aksi takdirde çerez gizli anahtarını belirten bir başlatma hatası vererek çalışmayı reddeder. Aşağıdaki komut, 32 baytlık bir anahtarı kodlayan 44 karakterlik bir değer üretir.
openssl rand -base64 32 | tr -- '+/' '-_'tr kullanımı görsel bir tercih değildir. Standart base64 formatını, oauth2-proxy'nin gizli anahtarı çözerken kullandığı URL güvenli alfabeye dönüştürür.
Bu değer için iki kural geçerlidir. Her dağıtım için farklı bir gizli anahtar kullanın. Aynı alan adı arkasında birden fazla oauth2-proxy örneği çalıştırıyorsanız, hepsine aynı gizli anahtarı verin; çünkü bir örnek tarafından şifrelenen çerezin diğerleri tarafından okunabilmesi gerekir.
oauth2-proxy yapılandırmasını yazma
İstemci gizli anahtarının (client secret) ps çıktısında görünmemesi için ayarları uzun bir komut satırı yerine bir dosyada tutun.
# /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'ye önündeki proxy'den gelen X-Forwarded-* başlıklarına güvenmesini söyler. Bu ayar olmadan oauth2-proxy, proxy'nin kendi adresini istemci adresi olarak kabul eder ve isteğin HTTPS üzerinden gelip gelmediğini yanlış değerlendirebilir.
trusted_proxy_ips, bu başlıkları hangi eşlerin sağlayabileceğini sınırlar. Varsayılan ayar her kaynağa güvenir; bu durum yalnızca http_address, oauth2-proxy'yi 127.0.0.1 üzerinde tuttuğu için burada güvenlidir. oauth2-proxy bir Docker ağı üzerinde dinleme yaptığında, bu ayarı reverse proxy'nizin adresi olarak belirleyin.
upstreams = ["static://202"], oauth2-proxy'nin kimliği doğrulanmış bir isteğe 202 yanıtı vermesini ve hiçbir şeyi proxy'lememesini sağlar; reverse proxy zaten proxy işlemini gerçekleştirdiği için forward auth'un tam olarak ihtiyaç duyduğu şey budur. Diğer dağıtım biçimi, oauth2-proxy'yi upstreams = ["http://127.0.0.1:3000"] ile ve hiçbir auth_request olmadan doğrudan istek yoluna yerleştirir. Bu, tek bir uygulama için daha basittir ancak on uygulama için ölçeklenemez.
email_domains = ["*"], sağlayıcınızın kimliğini doğrulayacağı her adresi kabul eder. Bunu kendi alan adınızla sınırlayın veya daha iyisi, sağlayıcıda bir grup bağlaması ile erişimi kısıtlayın; çünkü insanları zaten yönettiğiniz yer sağlayıcıdır.
Bunu systemd altında kendi kullanıcısı olarak çalıştırın:
# /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 çıktısının OK yazdırması, sürecin başladığını ve yapılandırmasını yüklediğini gösterir. Bu, oauth2-proxy'nin kendi sağlık kontrolü uç noktasıdır ve hiçbir zaman oturum istemez. Eğer hiçbir yanıt gelmiyorsa journalctl -u oauth2-proxy -n 50 dosyasını okuyun; hatalı bir sağlayıcı URL'si ve yanlış uzunlukta bir çerez gizli anahtarı başlangıçta başarısızlığa neden olur ve her ikisi de bu dosyada belirtilir.
Yönlendirme URI'sini sağlayıcınızda kaydedin
Sağlayıcınızda bir OIDC uygulaması oluşturun ve yönlendirme URI'sini yapılandırmadaki redirect_url ile tam olarak eşleşecek şekilde ayarlayın: https://app.example.com/oauth2/callback. Tam olarak ifadesi; şema, ana makine, port ve yolun karakteri karakterine eşleşmesi anlamına gelir. Sondaki bir eğik çizgi, URI'yi farklı kılar.
Bu, tüm kurulum sürecindeki en yaygın hata kaynağıdır ve oauth2-proxy devreye girmeden önce başarısız olur. Sağlayıcı, yetkilendirme isteğini reddeder ve kendi hata sayfasını görüntüler; bu nedenle oauth2-proxy günlüğünde hiçbir şey görünmez. Bunun belirtisi adres çubuğudur: tarayıcı hala sağlayıcınızın alan adındadır ve sorgu dizisi error=invalid_request değerini taşır ya da doğrudan redirect_uri sayfa adlarını içerir. Bunu gördüğünüzde, proxy yapılandırmasını değil, sağlayıcıdaki uygulama kaydını düzeltin.
Sağlayıcıdan issuer URL'sini yazmak yerine kopyalayın. oauth2-proxy, oidc_issuer_url adresine /.well-known/openid-configuration ekler ve başlangıçta bu keşif belgesini getirir. Önce kendiniz kontrol edin:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400authorization_endpoint anahtarını içeren bir JSON ilk kontrol noktasıdır; belgenin issuer değeri de oidc_issuer_url ile tam olarak eşleşmelidir. Bir 404 hatası veya HTML hata sayfası, adresin yanlış olduğu anlamına gelir ve oauth2-proxy de aynı 404 hatasıyla başlamayacaktır. Henüz bir sağlayıcı seçmediyseniz, Keycloak, Authentik ve Zitadel karşılaştırması avantaj ve dezavantajları ele alır; Authentik'i kendi SSO sunucunuz olarak çalıştırma rehberi ise bu kurulumun sağlayıcı tarafındaki adımlarını açıklar.
Nginx: auth_request
Nginx, dahili bir alt istek başlatan ve durum koduna göre dallanan auth_request ile ileri yönlendirmeli kimlik doğrulama (forward auth) gerçekleştirir.
# 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;
}
}Buradaki üç detay kritik öneme sahiptir. Boş bir Content-Length ile kullanılan proxy_pass_request_body off, nginx'in yalnızca başlıklara ihtiyaç duyan kimlik doğrulama uç noktasına istek gövdesini iletmesini engeller.
auth_request_set $auth_cookie ve add_header Set-Cookie ikilisi, yenilenmiş bir oturum çerezini tarayıcıya geri iletir. Bu ayar çıkarılırsa cookie_refresh sessizce hiçbir işlem yapmaz; çünkü nginx alt isteğin Set-Cookie değerini atar ve tarayıcı, oturum süresi dolana kadar eski değeri tutmaya devam eder. Bu ikili tek bir çerezi yönetir; bölünmüş oturum çerezleri diğer parçalar için ek işlem veya Redis oturum depolama gerektirir.
error_page 401 = @oauth2_signin, başarısız bir kontrolü giriş sayfasına yönlendirmeye dönüştüren kısımdır. Bu olmadan, kimliği doğrulanmamış bir ziyaretçi boş bir 401 Authorization Required sayfası ile karşılaşır ve ilerleyemez.
Yeniden yükleme yapmadan önce her zaman test edin:
sudo nginx -t && sudo systemctl reload nginxÇevredeki direktifler sizin için yeniyse, nginx reverse proxy yapılandırmasının anatomisi bu katmanın altındaki yapıyı açıklar.
Traefik: forwardAuth ara katmanı
Traefik, aynı iş için iki ara katmana (middleware) ihtiyaç duyar. Bunlardan biri kontrolü gerçekleştirir. Diğeri ise kontrol başarısız olduğunda giriş sayfasını sunar.
# 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}"Her ikisini de uygulamanızın önünde yer alan yönlendiriciye (router) bağlayın; oauth-errors ifadesini oauth-auth ifadesinden önce kullanın. oauth2-proxy servisini kendi yönlendiricisi üzerinde oauth.example.com adresinde yayınlayın; çünkü tarayıcının, kontrolü geçmeden /oauth2/sign_in ve /oauth2/callback adreslerine ulaşabilmesi gerekir. Bu ayrı giriş ana bilgisayarı için redirect_url değerini https://oauth.example.com/oauth2/callback olarak ayarlayın ve bu URI adresini sağlayıcıya kaydedin.
Yukarıdaki oauth2-proxy yapılandırması ile /oauth2/sign_in bir giriş sayfası oluşturur. Otomatik yönlendirme için oauth2-proxy içinde skip_provider_button = true ayarını yapın ve Traefik'in errors ayarları altına statusRewrites: {"401": 302} ekleyin. Bu yeniden yazma işlemi olmadan Traefik, otomatik yönlendirmeyi 401 durumu ile döndürür ve tarayıcı bunu takip etmez. Yalnızca yeniden yazma işlemi giriş akışını başlatmaz.
trustForwardHeader: true, gelen X-Forwarded-* başlıklarına güvenir; Traefik, orijinal ana bilgisayar ve URI bilgilerini oauth2-proxy servisine iletir. Bu seçenek güncel Traefik belgelerinde kullanımdan kaldırılmıştır. Bu ana bilgisayarı da kapsayacak şekilde whitelist_domains değerini ayarlayın; aksi takdirde oauth2-proxy, rd parametresini açık yönlendirme riski olarak değerlendirip reddeder ve kullanıcılar giriş yaptıktan sonra / adresine yönlendirilir. Bir Traefik sunucusu genellikle aynı anda birden fazla uygulamaya hizmet verir ve birden fazla Docker Compose uygulamasını tek bir Traefik örneği üzerinden yönlendirme konusu, bu yapının nasıl entegre edileceğini gösterir.
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
}
}Burada sıralama önemlidir. /oauth2/* bloğu önce gelir ve herhangi bir forward_auth içermez; çünkü oturum açmamış bir ziyaretçinin oturum açma ve geri çağırma yollarına erişebilmesi gerekir. Kontrol mekanizmasını bu yolların önüne koyarsanız, tarayıcı pes edene kadar oturum açma sayfası kendi kendine yönlendirme yapar.
copy_headers, kimlik bilgilerini upstream isteğine aktaran kısımdır ve yalnızca oauth2-proxy set_xauthrequest = true ile çalıştırıldığında değer üretir. Proxy'ler arasında seçim yapmak başlı başına bir konudur ve nginx, Caddy ve Traefik karşılaştırması bu süreci detaylandırır.
Oturum açma işlemi neden sürekli giriş sayfasına yönlendiriyor?
Sağlayıcı üzerinden oturum açarsınız, sağlayıcı sizi geri yönlendirir ve oauth2-proxy sizi tekrar giriş sayfasına gönderir. Bu döngü, oauth2-proxy'nin bir sonraki istekte geçerli bir oturumu kabul etmediği anlamına gelir. Oturum çerezi eksik olabilir veya mevcut olup doğrulamadan geçemiyor olabilir; örneğin, farklı örnekler (instances) farklı çerez sırları (cookie secrets) kullanıyorsa bu durum yaşanır. Tarayıcının geliştirici araçlarını açın, sağlayıcıdan gelen yönlendirmeden sonra /oauth2/callback adresine yapılan isteği bulun ve Set-Cookie yanıt başlığını inceleyin. Orada ayarlanan ancak bir sonraki istekte bulunmayan bir çerez, tarayıcının reddettiği çerezdir. Eğer çerez mevcutsa, sunucu günlüklerinde cookie signature not valid gibi doğrulama hatalarını kontrol edin ve tüm örneklerin aynı sırrı kullandığını doğrulayın.
Eksik olan çerez, oauth2-proxy'nin çıkış sırasında ayarladığı CSRF çerezi olduğunda akış döngüye girmez. Geri çağırma (callback) noktasında durur ve günlüklerde şu durum belirtilir:
No cookies were found in OAuth callback.veya başka bir çerez ulaştığı halde doğru olan ulaşmadığında:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF, siteler arası istek sahteciliği (cross-site request forgery) anlamına gelir ve bu çerez, geri çağırmanın onu başlatan oturum açma işlemiyle ilişkilendirilebilmesi için mevcuttur. Tarayıcı şu mesajı içeren bir 403 hata sayfası alır:
Login Failed: Unable to find a valid CSRF token. Please try again.Eksik çerezler aşağıdaki ilk üç nedeni paylaşır; saat sapması ise doğrulama hatalarının bir diğer nedenidir. Bu dört maddeyi sırasıyla kontrol edin.
- Tarayıcı siteye düz HTTP üzerinden ulaştığı sırada
cookie_secure = truekullanımı. Localhost haricinde, tarayıcılarSecureolarak işaretlenmiş bir çerezihttp://kökenli bir adreste saklamaz, bu nedenle çerez asla geri gönderilmez. TLS (transport layer security) sonlandırmasını düzgün yapın veya yalnızca localhost üzerinde test yaparkencookie_secure = falseayarını kullanın. - Adres çubuğundaki ana bilgisayar adını (hostname) kapsamayan bir
cookie_domainsdeğeri..example.com,app.example.comadresini kapsar ancakapp.example.netiçin hiçbir işlev görmez. - Tarayıcının çerezi düşürmesi. Sıkı bir gizlilik eklentisi veya üçüncü taraf çerez engelleme özelliği, giden yönlendirme ile geri çağırma arasındaki
_oauth2_proxy_csrfdeğerini veya sonrasındaki oturum çerezini silebilir. - Saat sapması. Sunucu saati sağlayıcının saatinden çok ilerideyse, kimlik belirteci (ID token) süresi dolmuş görünebilir ve doğrulama başarısız olur.
timedatectl,System clock synchronized: yeshatasını raporlamalıdır.
Bir başka neden de hiçbir yapılandırma hatası olmaksızın CSRF hatasına yol açar. Varsayılan olarak oauth2-proxy tek bir CSRF çerezi tutar, bu nedenle aynı anda oturum açmaya başlayan iki sekme birbirinin çerezinin üzerine yazar. cookie_csrf_per_request = true ayarı, her oturum açma işlemine kendine ait bir çerez atar.
Tahmin etmek yerine durumu sunucu tarafından izleyin:
sudo journalctl -u oauth2-proxy -fUygulamayı gizli bir pencerede yükleyin. Her istek durumuyla birlikte günlüğe kaydedilir; bu nedenle geri çağırmayı hemen takip eden bir giriş yönlendirmesi, kayıtlarda döngü olarak görünecektir.
Oturum açma işlemini atlaması gereken yollar: API'ler, webhook'lar ve websocket'ler
Forward auth, çerez tutan bir tarayıcı varsayar. Tarayıcısı olmayan istemciler bu yapıda çalışmaz.
Authorization: Bearer <token> gönderen bir API istemcisinin çerezi yoktur; bu nedenle, bearer-token kimlik doğrulaması etkinleştirilmediği sürece yukarıdaki proxy yapılandırmaları bu istemciyi oauth2-proxy giriş sayfasına yönlendirir. Bunun için iki temiz çözüm mevcuttur. skip_jwt_bearer_tokens = true ayarını yapmak, oauth2-proxy'nin yapılandırılmış sağlayıcıdan gelen ve bu istemci için kabul edilen bir hedef kitleye (audience) sahip geçerli bir JWT (JSON web token) bearer token'ını kabul etmesini sağlar; bu, API istemcileriniz sağlayıcıdan zaten uygun token'lar alıyorsa doğru yöntemdir. Token'ın aud değeri, client_id ile veya extra_jwt_issuers üzerinden yapılandırılmış bir hedef kitle ile eşleşmelidir. Aksi takdirde, yolu muaf tutun:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]Her değer, sorgu parametreleri hariç tutulmuş ve çözümlenmiş yol ile eşleştirilen bir düzenli ifadedir; isteğe bağlı olarak bir HTTP metodu ve = ile ön eklenebilir. POST=^/webhook/, webhook alıcısını POST isteklerine açık bırakırken, aynı yola giden bir insan kullanıcının giriş sayfasına yönlendirilmesini sağlar (kimlik doğrulama isteğinin orijinal metodu koruduğu varsayılır). Nginx auth_request ve Caddy forward_auth, GET kontrolleri yapar; bu nedenle, metoda özel muafiyetler bu kurulumlarda reverse proxy tarafında ayrı yönlendirme gerektirir. Her girdi kapınızda bir açık oluşturur; bu nedenle ifadeleri ^ ile sabitleyin ve istemcinin izin verdiği kadar dar tutun.
Bunlara güvenmeden önce v7.15.5 veya daha yeni bir sürüm çalıştırdığınızdan emin olun. v7.5.0 sonrası ve v7.15.5 öncesi sürümler, nokta segmentleri, çift eğik çizgi veya noktalı virgül içeren isteklerle korumalı bir yolun muaf tutulması konusunda kandırılabilirdi (GHSA-63jm-59jj-478j uyarısı); ifadeleri sabitlemek de bunu engellemiyordu. Düzeltilmiş sürüm, bu tür belirsiz yolları muaf tutmayı reddeder; bu nedenle yükseltme sonrasında genel yollarınızın hala eşleştiğini kontrol edin.
Websocket'ler insanların yanlış anladığı bir konudur. Yükseltme (upgrade) isteği, diğer tüm isteklerle aynı çerezleri taşıyan sıradan bir HTTP GET isteğidir; bu nedenle kontrolü normal şekilde geçer ve muafiyete ihtiyaç duymaz. Sorun, çevresindeki proxy yapılandırmasında yaşanır. Korunan konumda Upgrade ve Connection başlıkları olmadığında, yükseltme asla tamamlanmaz ve uygulamanın istemcisi tarayıcı konsolunda WebSocket connection ... failed mesajı ile sürekli yeniden deneme yapar. Yolu muaf tutmak burada hiçbir şeyi düzeltmez, çünkü istek zaten yetkilendirilmiştir.
Gerçek bir sınırlama mevcuttur. Kontrol, yükseltme sırasında bir kez çalışır. Saatlerce açık kalan bir websocket asla yeniden kontrol edilmez; bu nedenle sağlayıcınızdan bir kullanıcıyı silmek, halihazırda sahip oldukları soketi kapatmaz. Canlı bağlantıları kesmek için uygulamayı yeniden başlatın.
Oturum depolama ve aşırı büyüyen çerezler
Varsayılan olarak tüm oturum, cookie_secret ile şifrelenmiş şekilde çerez içinde tutulur. Bu durum, oauth2-proxy'nin durumsuz (stateless) kalmasını sağlar ve ek bir servis gerektirmez. Ancak tarayıcılar çerez boyutunu yaklaşık 4 KB ile sınırladığından, bu yöntemin bir üst sınırı vardır. ID token uzun bir grup talebi listesi taşıdığında, oauth2-proxy oturumu _oauth2_proxy_0, _oauth2_proxy_1 ve devamı parçalara böler. Parça sayısı arttıkça istek başlıkları o kadar büyür ki, uygulama isteği görmeden önce nginx 400 Request Header Or Cookie Too Large hatası döndürür.
Bu durum gerçekleştiğinde oturumu sunucu tarafına taşıyın:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"Bu durumda tarayıcı kısa bir bilet tutar ve şifrelenmiş oturum Redis üzerinde saklanır. Bunun maliyeti, sürekli çalışması gereken bir servistir: Redis çökerse, oauth2-proxy oturumları yükleyemez; depolanan oturum verilerinin kaybolması, tüm kullanıcıların tekrar giriş yapmasını zorunlu kılar. Çerez deposunun kendi maliyeti ise, aynı oturumu aynı anda yenileyen iki isteğin çakışarak yeniden girişi zorunlu kılabilmesidir.
Forward auth size ne sağlamaz
Bu, kapıdaki bir güvenlik kontrolüdür. Uygulama içindeki yetkilendirme mekanizması değildir; bu ayrım, yaklaşımın durumunuza uygun olup olmadığını belirler.
Kullanıcı kapıdan geçtikten sonra uygulama, her zaman gördüğü şeyi görmeye devam eder. Uygulamanın kendi rol tanımları varsa, uygulama başlık tabanlı kimlik doğrulamayı desteklemediği ve bir başlığı hesapla eşleştirmediği sürece forward auth bu rolleri doldurmaz. Grafana, auth.proxy ayarları aracılığıyla bunu yapar. Çoğu self-hosted uygulama bunu desteklemediği için, kapıdan geçen herkes uygulama nezdinde aynı kimliğe sahiptir ve bu kimlik genellikle yönetici yetkilerine sahiptir.
Ayrıca bu yöntem, uygulamanın kendi API token'larını korumaz. Uygulama tarafından verilen kişisel erişim token'ı, oauth2-proxy'ye değil uygulamaya kimlik doğrulaması yapar; bu nedenle kapı önüne yerleştirildiğinde token çalışmayı durdurur. API yolunu muaf tutarak erişimi geri getirdiğinizde, o yolu koruyan tek şey söz konusu token olur. Artık tek bir servis üzerinde iki farklı kimlik doğrulama sistemi çalıştırırsınız ve SSO bunlardan yalnızca birini kapsar.
Erişim iptali üçüncü eksikliktir. Sağlayıcınızda bir kullanıcıyı silmek yeni girişleri durdurur, ancak oauth2-proxy mevcut oturumu cookie_refresh süresi dolana kadar sağlayıcı ile tekrar kontrol etmez. Yenileme (refresh) kapalıyken, oturum çerezi süresi dolana kadar geçerli kalır. cookie_expire varsayılan olarak 168 saattir; bu da sistemden çıkardığınız birinin bir hafta boyunca erişiminin sürebileceği anlamına gelir. cookie_refresh değerini bir saat gibi kısa bir süreye ayarlayın. Sağlayıcı, kullanıcının yenileme token'ı artık geçerli olmadığı için yenileme isteğini reddettiğinde, oauth2-proxy oturumu temizler ve yenilemeyi tetikleyen bir sonraki istekte yeni bir giriş zorunlu kılar. Yenileme özelliği her sağlayıcı tarafından desteklenmez, bu nedenle kendi sağlayıcınızla test edin.
Denetim izi de kapıda sona erer. oauth2-proxy kimin ne zaman geçtiğini günlüğe kaydeder. Uygulama ise isimsiz bir oturumu günlüğe kaydeder. Bir ayarı kimin değiştirdiğini tespit etmeniz gerekirse, uygulamadaki başlık tabanlı kimlik en alt sınırdır; gerçek kullanıcı bazlı hesaplar ise en güvenilir çözümdür.
SSO maliyetini karşılamanın daha mantıklı olduğu durumlar
Forward auth, bir uygulamanın hiçbir giriş mekanizması yoksa veya paylaşımlı tek bir parola kullanılıyorsa, kullanıcı ekleyip çıkarabileceğiniz merkezi bir nokta oluşturmak için doğru araçtır. Bu yöntem bir öğleden sonranızı alır, fazladan bir süreç gerektirir ve HTTP ile konuşan her uygulama ile çalışır.
Aynı uygulama içinde farklı kişilerin farklı izinlere ihtiyaç duyduğu durumlarda ise yanlış araçtır. Bir geçit (gate), "Ana panelleri düzenleyebilir, Bo ise sadece görüntüleyebilir" gibi bir kuralı ifade edemez. Eğer satıcı bir SSO katmanı satıyorsa, aslında satın aldığınız şey genellikle grup-rol eşleme özelliğidir; bunu header'lar ve proxy kuralları ile yeniden oluşturmak, ücretini ödemekten daha kırılgan bir yapıdır. Karar vermeden önce bu SSO katmanlarının arkasındaki fiyatlandırma modeli hakkında bilgi edinmek faydalı olacaktır.
Tarayıcı çerezlerini taşımayan bir mobil veya masaüstü istemcisine sahip her uygulama, her istekte bu geçit ile sorun yaşayacaktır.
FAQ
Forward auth nedir?
Forward auth, reverse proxy'nin gelen her isteği yukarı akışa (upstream) iletmeden önce ayrı bir kimlik doğrulama servisine sorduğu bir yöntemdir. Proxy, istek başlıklarını /oauth2/auth gibi bir uç noktaya gönderir ve dönen durum kodunu okur. 202 kodu "izin verildi" anlamına gelir ve orijinal istek uygulamaya iletilir. 401 kodu ise geçerli bir oturum olmadığını belirtir; bu durumda proxy, tarayıcıyı giriş sayfasına yönlendirir. Nginx bu işlemi auth_request direktifiyle, Traefik forwardAuth ara katman yazılımıyla (middleware), Caddy ise forward_auth ile gerçekleştirir.
oauth2-proxy neden beni sürekli giriş sayfasına yönlendiriyor?
Oturum çerezi eksik veya doğrulama başarısız olduğu için her kontrol geçersiz bir oturum bulur ve sizi tekrar giriş sayfasına gönderir. Farklı çerez sırları (cookie secrets) kullanan örnekler, birbirlerinin çerezlerini reddeder. Bir diğer neden, tarayıcının düz HTTP üzerinden ulaştığı bir sitede cookie_secure = true kullanılmasıdır; çünkü localhost haricinde tarayıcılar, http:// kökenli bir adreste Secure çerezi saklamaz. Ayrıca adres çubuğundaki ana makine adını (hostname) kapsamayan bir cookie_domains değeri olup olmadığını kontrol edin. Hangi çerezin eksik olduğunu görmek için tarayıcınızın geliştirici araçlarındaki /oauth2/callback yanıtında yer alan Set-Cookie başlığını inceleyin. Eğer çerez dönüyorsa, sunucu günlüklerinde doğrulama hatalarını kontrol edin. Eğer eksik olan CSRF çerezi ise, döngü yerine Login Failed: Unable to find a valid CSRF token. Please try again. yazan bir 403 sayfası alırsınız ve günlüklerde hiçbir çerez ulaşmadığında No cookies were found in OAuth callback. ifadesi yer alır.
Bir API istemcisinin veya webhook'un oauth2-proxy üzerinden geçmesine nasıl izin veririm?
Sabitlenmiş (anchored) bir düzenli ifade ile skip_auth_routes kullanın; isteğe bağlı olarak bunu tek bir HTTP metoduna kısıtlayın (örneğin POST=^/webhook/). Bu muafiyetlerdeki kritik bir atlatma açığını gideren v7.15.5 veya daha yeni bir sürümü çalıştırdığınızdan emin olun. Metoda özel muafiyetler, kimlik doğrulama isteğinin orijinal metodu korumasını gerektirir; Nginx ve Caddy örnekleri GET kontrolleri yaptığı için bu muafiyetleri reverse proxy'nin yönlendirme ayarlarında yönetin. Eğer API istemcileriniz zaten yapılandırılmış sağlayıcı tarafından verilmiş ve kabul edilen bir hedef kitleye (audience) sahip geçerli JWT'lere sahipse, skip_jwt_bearer_tokens = true bu belirteçleri çerez yerine kabul eder ve yolu korumaya devam eder. Hedef kitle, client_id ile veya extra_jwt_issuers üzerinden yapılandırılan bir kitle ile eşleşmelidir. skip_auth_routes içinde listelenen her şey herkes için kimlik doğrulaması gerektirmez, bu nedenle her ifadeyi çağrının izin verdiği ölçüde dar tutun.
oauth2-proxy uygulamaya kullanıcı bazlı yetkiler sağlar mı?
Hayır. Bu bir yetkilendirme sistemi değil, bir kapıdır. Uygulamaya kimin ulaşacağına karar verir; uygulama kimlik başlıklarını okuyup bunları hesaplarla eşleştirmediği sürece, kapıdan geçen herkes uygulama için aynı görünür. Grafana bunu auth.proxy ayarlarıyla yapabilir. Çoğu self-hosted uygulama bunu yapamaz, bu nedenle kapıdan geçen herkes uygulamanın çalıştığı tek bir kimliği paylaşır.
Birisi kimlik başlığını kendisi ayarlayarak oauth2-proxy'yi atlatabilir mi?
Evet, eğer uygulamaya doğrudan ulaşabiliyorsa. Kimlik bilgisi, X-Auth-Request-Email gibi düz bir başlık olarak gelir ve uygulama ne alırsa ona güvenir. Uygulama portuna bağlantı açabilen herkes bu başlığı göndererek herhangi bir kullanıcı gibi davranabilir. Uygulamayı 127.0.0.1 adresine bağlayın veya yayınlanmış bir portu olmayan dahili bir Docker ağında tutun ve bunu sudo ss -tlnp ile doğrulayın.