oauth2-proxy का उपयोग करके किसी भी ऐप में SSO कैसे जोड़ें
बिना लॉगिन वाले ऐप्स को OIDC के पीछे सुरक्षित करें। Nginx या Traefik के साथ oauth2-proxy कॉन्फ़िगर करें और कुकी या रीडायरेक्ट की समस्याओं से बचने के सटीक तरीके यहाँ जानें।
Forward auth: बिना लॉगिन वाले application में SSO कैसे जोड़ें
oauth2-proxy उन applications को single sign-on की सुविधा देता है जिनमें अपना कोई लॉगिन सिस्टम नहीं होता। यह इस तरह काम करता है कि application के सामने लगा reverse proxy हर request को रोकता है, oauth2-proxy से पूछता है कि क्या request में valid session है, और केवल तभी request को upstream भेजता है जब जवाब 'हाँ' हो। Application के कोड में कोई बदलाव नहीं करना पड़ता, क्योंकि application को इस जाँच का पता ही नहीं चलता।
यह जाँच एक अतिरिक्त HTTP request है। Proxy आने वाली request के headers की एक कॉपी /oauth2/auth को भेजता है और status code पढ़ता है। 202 का मतलब है कि जाँच सफल रही, इसलिए proxy मूल request को app तक भेज देता है। 401 का मतलब है कि कोई valid session नहीं है, इसलिए proxy ब्राउज़र को /oauth2/sign_in पर भेज देता है, जो डिफ़ॉल्ट रूप से एक लॉगिन पेज दिखाता है। /oauth2/start आपके identity provider पर OpenID Connect (OIDC) लॉगिन शुरू करता है; skip_provider_button = true इसे /oauth2/sign_in के माध्यम से स्वचालित रूप से शुरू करवाता है। OIDC, OAuth 2.0 के ऊपर बनी identity layer है, और provider वही है जिसे आप लॉगिन के लिए पहले से उपयोग कर रहे हैं।
इस पैटर्न का हर reverse proxy में एक नाम है। Nginx इस directive को auth_request कहता है। Traefik इसे forwardAuth middleware कहता है। Caddy इसे forward_auth के रूप में लिखता है। Sub-request का जवाब देने वाली service भी बदली जा सकती है। oauth2-proxy एक सामान्य विकल्प है क्योंकि यह सीधे OIDC का उपयोग करता है और इसे अपने किसी डेटाबेस की आवश्यकता नहीं होती।
कॉन्फ़िगरेशन लिखने से पहले ट्रस्ट बाउंड्री निर्धारित करें
सफल जांच के बाद, oauth2-proxy पहचान को रिस्पॉन्स हेडर के रूप में लौटाता है, और रिवर्स प्रॉक्सी उन्हें अपस्ट्रीम रिक्वेस्ट पर कॉपी कर देता है। 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: मैपिंग हटा दें और इसे केवल इंटरनल नेटवर्क पर रखें, ताकि केवल प्रॉक्सी कंटेनर ही इससे कनेक्ट हो सके। बेयर होस्ट पर, ऐप को 0.0.0.0:3000 के बजाय 127.0.0.1:3000 पर बाइंड करें। फिर जांचें कि आपने वास्तव में क्या एक्सपोज़ किया है:
sudo ss -tlnp | grep 30000.0.0.0:3000 वाली लाइन का मतलब है कि ऐप पब्लिक IP पर जवाब दे रहा है और आपका गेट केवल दिखावटी है। 127.0.0.1:3000 वह है जो आप चाहते हैं। फ़ायरवॉल नियम एक उपयोगी दूसरी परत है, लेकिन बाइंड एड्रेस वह है जो किसी अन्य टूल द्वारा आपके रूल्सेट को फ्लश करने के बाद भी सुरक्षित रहता है।
oauth2-proxy इंस्टॉल करें
अक्टूबर 2026 तक, वर्तमान release v7.15.5 है, जिसे 1 अक्टूबर 2026 को प्रकाशित किया गया था। यह दो गंभीर सुरक्षा सलाहों (security advisories) को ठीक करता है, जिनमें से एक skip_auth_routes का बाईपास है जो v7.5.0 के बाद के हर release को प्रभावित करता है, इसलिए इससे पुराना कोई भी वर्ज़न इंस्टॉल न करें। बाइनरी इंस्टॉल करें और डाउनलोड को सत्यापित करें:
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 secret जनरेट करें
Session cookie एन्क्रिप्टेड होती है और cookie_secret इसकी कुंजी (key) है। एन्क्रिप्शन कुंजी का आकार ठीक 16, 24 या 32 बाइट्स का होना चाहिए, क्योंकि यह एक AES (advanced encryption standard) कुंजी के रूप में कार्य करती है। oauth2-proxy एक URL-safe base64 मान स्वीकार करता है जो डिकोड होने पर इन लंबाइयों में से एक हो, या फिर इतनी ही लंबाई की एक raw secret स्वीकार करता है; अन्यथा, यह cookie secret का नाम बताते हुए स्टार्टअप त्रुटि के साथ शुरू होने से मना कर देता है। नीचे दिया गया कमांड 32-बाइट कुंजी को एन्कोड करने वाला 44-कैरेक्टर का मान तैयार करता है।
openssl rand -base64 32 | tr -- '+/' '-_'tr केवल दिखावे के लिए नहीं है। यह मानक base64 को उस URL-safe वर्णमाला में बदलता है जिसका उपयोग oauth2-proxy secret को डिकोड करते समय करता है।
इस मान के लिए दो नियम हैं। प्रत्येक डिप्लॉयमेंट के लिए एक अलग secret का उपयोग करें। और जब आप एक ही डोमेन के पीछे एक से अधिक oauth2-proxy इंस्टेंस चलाते हैं, तो उन सभी को एक ही secret दें, क्योंकि एक इंस्टेंस द्वारा एन्क्रिप्ट की गई 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 नेटवर्क पर लिसन करता है, तो इसे अपने रिवर्स प्रॉक्सी के पते पर सेट करें।
upstreams = ["static://202"], oauth2-proxy को एक प्रमाणित अनुरोध पर 202 उत्तर देने और कुछ भी प्रॉक्सी न करने के लिए मजबूर करता है, जो कि forward auth के लिए बिल्कुल सही है, क्योंकि प्रॉक्सी का काम रिवर्स प्रॉक्सी द्वारा किया जाता है। डिप्लॉयमेंट का दूसरा तरीका oauth2-proxy को सीधे अनुरोध पथ में upstreams = ["http://127.0.0.1:3000"] के साथ और बिना किसी auth_request के रखता है। यह एक ऐप के लिए सरल है लेकिन दस ऐप्स के लिए स्केलेबल नहीं है।
email_domains = ["*"] उन सभी पतों को स्वीकार करता है जिन्हें आपका प्रदाता प्रमाणित करेगा। इसे अपने डोमेन तक सीमित करें, या बेहतर होगा कि प्रदाता में group binding के साथ एक्सेस को प्रतिबंधित करें, क्योंकि प्रदाता ही वह स्थान है जहाँ आप पहले से ही लोगों को मैनेज करते हैं।
इसे 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 प्रिंट होने का मतलब है कि प्रोसेस शुरू हो गई है और उसने अपना कॉन्फ़िगरेशन लोड कर लिया है। यह oauth2-proxy का अपना health endpoint है और यह कभी भी सेशन के लिए नहीं पूछता है। यदि कोई उत्तर नहीं मिलता है, तो journalctl -u oauth2-proxy -n 50 पढ़ें, क्योंकि गलत issuer URL और गलत लंबाई वाला cookie secret दोनों स्टार्टअप पर विफल हो जाते हैं और दोनों ही इसका कारण बताते हैं।
अपने प्रदाता के साथ redirect URI रजिस्टर करें
अपने प्रदाता में एक OIDC एप्लिकेशन बनाएँ और उसके redirect URI को कॉन्फ़िगरेशन के redirect_url पर सेट करें: https://app.example.com/oauth2/callback। 'बिल्कुल' का अर्थ है कि स्कीम, होस्ट, पोर्ट और पाथ का हर एक अक्षर मेल खाना चाहिए। अंत में लगा एक स्लैश (/) इसे एक अलग URI बना देता है।
पूरे सेटअप में यह सबसे आम विफलता है, और यह oauth2-proxy के शामिल होने से पहले ही विफल हो जाती है। प्रदाता ऑथराइजेशन अनुरोध को अस्वीकार कर देता है और अपना स्वयं का एरर पेज दिखाता है, इसलिए oauth2-proxy लॉग में कुछ भी दिखाई नहीं देता है। इसकी पहचान एड्रेस बार से होती है: ब्राउज़र अभी भी आपके प्रदाता के डोमेन पर है, और क्वेरी स्ट्रिंग में सीधे error=invalid_request या पेज का नाम redirect_uri दिखाई देता है। जब आप ऐसा देखें, तो प्रॉक्सी कॉन्फ़िगरेशन के बजाय प्रदाता में एप्लिकेशन रिकॉर्ड को ठीक करें।
issuer URL को टाइप करने के बजाय प्रदाता से कॉपी करें। oauth2-proxy, oidc_issuer_url में /.well-known/openid-configuration जोड़ता है और स्टार्टअप पर उस डिस्कवरी डॉक्यूमेंट को फेच करता है। इसे पहले स्वयं जाँचें:
curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400JSON जिसमें authorization_endpoint की हो, वह पहली जाँच है; डॉक्यूमेंट का issuer भी oidc_issuer_url से बिल्कुल मेल खाना चाहिए। 404 या HTML एरर पेज का मतलब है कि यह गलत है, और oauth2-proxy उसी 404 पर स्टार्ट होने में विफल हो जाएगा। यदि आपने अभी तक कोई प्रदाता नहीं चुना है, तो Keycloak, Authentik और Zitadel की तुलना उनके अंतरों को कवर करती है, और Authentik को अपने स्वयं के SSO सर्वर के रूप में चलाना इस सटीक सेटअप के प्रदाता वाले हिस्से को विस्तार से समझाता है।
Nginx: auth_request
Nginx, auth_request का उपयोग करके forward auth करता है, जो एक internal sub-request शुरू करता है और उसके status code के आधार पर निर्णय लेता है।
# 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;
}
}इसमें तीन विवरण महत्वपूर्ण हैं। खाली Content-Length के साथ proxy_pass_request_body off का उपयोग करने से nginx को authentication endpoint पर request body भेजने से रोका जाता है, क्योंकि endpoint को केवल headers की आवश्यकता होती है।
auth_request_set $auth_cookie और add_header Set-Cookie की जोड़ी browser को refreshed session cookie वापस भेजती है। यदि इसे हटा दिया जाए, तो cookie_refresh चुपचाप कुछ नहीं करेगा, क्योंकि nginx sub-request के Set-Cookie को discard कर देता है और session expire होने तक browser पुरानी value ही रखता है। यह जोड़ी केवल एक cookie को संभालती है; split session cookies के लिए अन्य भागों हेतु अतिरिक्त handling या Redis session storage की आवश्यकता होती है।
error_page 401 = @oauth2_signin वह निर्देश है जो एक failed check को login page पर भेजता है। इसके बिना, एक unauthenticated visitor को केवल एक खाली 401 Authorization Required page दिखाई देगा और आगे बढ़ने का कोई रास्ता नहीं मिलेगा।
Reload करने से पहले हमेशा test करें:
sudo nginx -t && sudo systemctl reload nginxयदि आसपास के directives आपके लिए नए हैं, तो nginx reverse proxy config की संरचना इस परत के नीचे की जानकारी प्रदान करती है।
Traefik: forwardAuth middleware
Traefik को एक ही काम के लिए दो middlewares की आवश्यकता होती है। एक जाँच (check) चलाता है। दूसरा जाँच विफल होने पर login page दिखाता है।
# 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}"दोनों को उस router से जोड़ें जो आपके app के सामने है, जिसमें oauth-errors को oauth-auth से पहले रखें। oauth2-proxy को उसके अपने router पर oauth.example.com पर publish करें, क्योंकि browser को /oauth2/sign_in और /oauth2/callback तक जाँच से गुजरे बिना पहुँचना होता है। इस अलग login host के लिए, redirect_url को https://oauth.example.com/oauth2/callback पर सेट करें और उस URI को provider के साथ register करें।
ऊपर दिए गए oauth2-proxy config के साथ, /oauth2/sign_in एक login page रेंडर करता है। इसके बजाय automatic redirect के लिए, oauth2-proxy में skip_provider_button = true सेट करें और Traefik की errors settings के अंतर्गत statusRewrites: {"401": 302} जोड़ें। उस rewrite के बिना, Traefik 401 status के साथ automatic redirect लौटाता है और browser उसका पालन नहीं करता है। केवल rewrite करने से login flow शुरू नहीं होता है।
trustForwardHeader: true आने वाले X-Forwarded-* headers पर भरोसा करता है; Traefik मूल host और URI को oauth2-proxy तक पहुँचाता है। यह विकल्प वर्तमान Traefik documentation में deprecated है। उस host को कवर करने के लिए whitelist_domains सेट करें, अन्यथा oauth2-proxy open-redirect जोखिम के कारण rd parameter को हटा देता है और login के बाद हर कोई / पर पहुँच जाता है। एक Traefik box आमतौर पर एक साथ कई apps को संभालता है, और एक Traefik instance के माध्यम से कई Docker Compose apps को route करना उस router layout को दिखाता है जिसमें यह जुड़ता है।
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 नहीं होता है, क्योंकि जो visitor logged in नहीं है, उसे sign-in और callback paths तक पहुँचना होता है। यदि आप इन paths के आगे check लगा देंगे, तो login खुद को ही redirect करता रहेगा जब तक कि browser हार न मान ले।
copy_headers वह है जो identity को upstream request पर ले जाता है, और यह केवल तभी values उत्पन्न करता है जब oauth2-proxy को set_xauthrequest = true के साथ चलाया जाता है। proxies के बीच चुनाव करना अपने आप में एक अलग प्रश्न है, और nginx, Caddy और Traefik की तुलना इस पर विस्तार से चर्चा करती है।
लॉगिन पेज पर वापस लूप क्यों होता है?
आप प्रदाता (provider) के पास साइन इन करते हैं, वह आपको वापस भेजता है, और oauth2-proxy आपको फिर से लॉगिन पर भेज देता है। इस लूप का मतलब है कि oauth2-proxy अगली रिक्वेस्ट पर एक वैध सत्र (valid session) स्वीकार नहीं कर रहा है। सत्र कुकी (session cookie) गायब हो सकती है, या वह मौजूद हो सकती है लेकिन सत्यापन (validation) में विफल हो सकती है, उदाहरण के लिए जब इंस्टेंस अलग-अलग कुकी सीक्रेट्स का उपयोग करते हैं। ब्राउज़र के डेवलपर टूल्स खोलें, प्रदाता से वापस आने वाले रीडायरेक्ट के बाद /oauth2/callback के लिए रिक्वेस्ट ढूंढें, और इसके Set-Cookie रिस्पॉन्स हेडर को पढ़ें। जो कुकी वहां सेट की गई है और अगली रिक्वेस्ट में गायब है, वही वह कुकी है जिसे ब्राउज़र अस्वीकार कर रहा है। यदि यह मौजूद है, तो सत्यापन त्रुटियों जैसे cookie signature not valid के लिए सर्वर लॉग की जांच करें और पुष्टि करें कि सभी इंस्टेंस एक ही सीक्रेट का उपयोग करते हैं।
जब गायब होने वाली कुकी वह CSRF कुकी होती है जिसे oauth2-proxy ने बाहर जाते समय सेट किया था, तो फ्लो लूप नहीं करता है। यह कॉलबैक पर रुक जाता है, और लॉग इस स्थिति का नाम बताता है:
No cookies were found in OAuth callback.या, जब कोई अन्य कुकी पहुंच जाती है लेकिन सही वाली नहीं पहुंचती:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF का अर्थ है क्रॉस-साइट रिक्वेस्ट फोर्जरी, और यह कुकी इसलिए मौजूद होती है ताकि एक कॉलबैक को उस लॉगिन से जोड़ा जा सके जिसने इसे शुरू किया था। ब्राउज़र को एक 403 एरर पेज मिलता है जिसमें यह होता है:
Login Failed: Unable to find a valid CSRF token. Please try again.गायब कुकीज़ के नीचे दिए गए पहले तीन कारण समान हैं; क्लॉक ड्रिफ्ट (clock drift) सत्यापन विफलताओं का एक और कारण है। इन चारों की क्रमवार जांच करें।
cookie_secure = trueजबकि ब्राउज़र सादे HTTP पर साइट तक पहुंचा। localhost को छोड़कर, ब्राउज़रSecureचिह्नित कुकी कोhttp://ऑरिजिन पर स्टोर नहीं करेगा, इसलिए इसे कभी वापस नहीं भेजा जाता है। TLS (ट्रांसपोर्ट लेयर सिक्योरिटी) को ठीक से समाप्त (terminate) करें, या केवल localhost पर परीक्षण करते समयcookie_secure = falseसेट करें।- एक
cookie_domainsमान जो एड्रेस बार में होस्टनाम को कवर नहीं करता है।.example.com,app.example.comको कवर करता है औरapp.example.netके लिए कुछ भी नहीं करता है। - ब्राउज़र कुकी को ड्रॉप कर रहा है। एक सख्त प्राइवेसी एक्सटेंशन या थर्ड-पार्टी कुकी ब्लॉकिंग आउटबाउंड रीडायरेक्ट और कॉलबैक के बीच
_oauth2_proxy_csrfको, या उसके बाद सत्र कुकी को हटा सकता है। - क्लॉक ड्रिफ्ट। यदि सर्वर की घड़ी प्रदाता की घड़ी से काफी आगे है, तो ID टोकन समाप्त (expired) दिखाई दे सकता है और सत्यापन में विफल हो सकता है।
timedatectlकोSystem clock synchronized: yesरिपोर्ट करना चाहिए।
एक और कारण CSRF त्रुटि उत्पन्न करता है जिसमें कुछ भी गलत कॉन्फ़िगर नहीं होता है। डिफ़ॉल्ट रूप से oauth2-proxy एक एकल CSRF कुकी रखता है, इसलिए एक ही समय में लॉगिन शुरू करने वाले दो टैब एक-दूसरे को ओवरराइट कर देते हैं। cookie_csrf_per_request = true प्रत्येक लॉगिन को अपना अलग कुकी देता है।
अनुमान लगाने के बजाय सर्वर साइड से इसे होते हुए देखें:
sudo journalctl -u oauth2-proxy -fऐप को प्राइवेट विंडो में लोड करें। प्रत्येक रिक्वेस्ट को उसके स्टेटस के साथ लॉग किया जाता है, इसलिए कॉलबैक के तुरंत बाद लॉगिन पर दूसरा रीडायरेक्ट लूप है, जो रिकॉर्ड पर है।
वे पाथ (paths) जिन्हें लॉगिन से बाहर रखना है: APIs, webhooks और websockets
Forward auth यह मानकर चलता है कि ब्राउज़र में cookie मौजूद है। बिना ब्राउज़र वाले callers यहाँ विफल हो जाते हैं।
जो API client Authorization: Bearer <token> भेजता है, उसके पास cookie नहीं होती है। इसलिए, यदि bearer-token authentication सक्षम नहीं है, तो ऊपर दी गई proxy configurations उसे oauth2-proxy के लॉगिन पेज पर भेज देती हैं। इसके दो स्पष्ट समाधान हैं। skip_jwt_bearer_tokens = true सेट करने से oauth2-proxy कॉन्फ़िगर किए गए issuer से एक वैध JWT (JSON web token) bearer token स्वीकार करने लगता है, बशर्ते वह इस client के लिए मान्य audience का हो। यह तब सही है जब आपके API clients पहले से ही provider से उपयुक्त tokens प्राप्त कर रहे हों। token का aud, client_id से मेल खाना चाहिए या extra_jwt_issuers के माध्यम से कॉन्फ़िगर किए गए audience से मिलना चाहिए। अन्यथा, पाथ को छूट (exempt) दें:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]प्रत्येक मान एक regular expression है जिसका मिलान query parameters के बिना डिकोड किए गए पाथ से किया जाता है, जिसमें वैकल्पिक रूप से HTTP method और = को prefix किया जा सकता है। POST=^/webhook/ webhook receiver को POST के लिए खुला छोड़ देता है, जबकि उसी पाथ पर ब्राउज़ करने वाला व्यक्ति अभी भी लॉगिन पेज पर ही जाता है, बशर्ते authentication request मूल method को सुरक्षित रखे। Nginx auth_request और Caddy forward_auth GET चेक करते हैं, इसलिए उन setups में method-specific छूट के लिए reverse proxy पर अलग routing की आवश्यकता होती है। प्रत्येक entry आपके गेट में एक छेद की तरह है, इसलिए expressions को ^ के साथ anchor करें और उन्हें उतना ही सीमित रखें जितना caller अनुमति देता है।
इन पर निर्भर होने से पहले v7.15.5 या उसके बाद का वर्शन चलाएं। v7.5.0 के बाद के पुराने releases को ऐसी request के साथ एक सुरक्षित पाथ से छूट देने के लिए धोखा दिया जा सकता था जिसमें dot segments, दोहरा leading slash या semicolon का उपयोग किया गया हो (advisory GHSA-63jm-59jj-478j), और expressions को anchor करने से भी यह नहीं रुकता था। फिक्स किया गया release ऐसे अस्पष्ट पाथ को छूट देने से इनकार करता है, इसलिए अपग्रेड करने के बाद जांच लें कि आपके public routes अभी भी मेल खाते हैं या नहीं।
Websockets वह मामला है जिसे लोग गलत समझते हैं। upgrade request एक सामान्य HTTP GET होती है जिसमें अन्य requests की तरह ही cookies होती हैं, इसलिए यह सामान्य रूप से चेक पास कर लेती है और इसे किसी छूट की आवश्यकता नहीं होती है। समस्या इसके चारों ओर proxying में आती है। यदि protected location पर Upgrade और Connection headers न हों, तो upgrade कभी पूरा नहीं होता और app का client ब्राउज़र कंसोल में WebSocket connection ... failed संदेश के साथ बार-बार retry करता रहता है। वहां पाथ को छूट देने से कुछ ठीक नहीं होता, क्योंकि request पहले ही अधिकृत (authorised) हो चुकी होती है।
एक वास्तविक सीमा लागू होती है। चेक केवल एक बार, upgrade के समय चलता है। जो websocket घंटों तक खुला रहता है, उसकी दोबारा जांच नहीं होती, इसलिए अपने provider में से user को हटाने पर भी उनका पहले से खुला socket बंद नहीं होता। लाइव कनेक्शन्स को काटने के लिए app को restart करें।
Session storage, और वह cookie जो बहुत बड़ी हो जाती है
डिफ़ॉल्ट रूप से, पूरा session cookie के अंदर रहता है, जिसे आपके cookie_secret से encrypt किया जाता है। यह oauth2-proxy को stateless रखता है और किसी अतिरिक्त service की आवश्यकता नहीं होती। इसकी एक सीमा भी है, क्योंकि browsers cookie को लगभग 4 KB पर सीमित कर देते हैं। जब ID token में group claims की एक लंबी सूची होती है, तो oauth2-proxy session को _oauth2_proxy_0, _oauth2_proxy_1 और उसके आगे विभाजित कर देता है, और कुछ हिस्सों के बाद request headers इतने बड़े हो जाते हैं कि app के request देखने से पहले ही nginx 400 Request Header Or Cookie Too Large का उत्तर दे देता है।
ऐसा होने पर session को server-side पर ले जाएँ:
session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"इसके बाद browser एक छोटा ticket रखता है, और encrypted session Redis में रहता है। इसकी कीमत एक ऐसी service है जिसे चालू रहना पड़ता है: यदि Redis down हो जाता है, तो oauth2-proxy sessions को load नहीं कर सकता; stored session data खोने से सभी users को फिर से login करना पड़ता है। cookie store की अपनी एक कीमत है, जो यह है कि एक ही समय में एक ही session को refresh करने वाली दो requests आपस में टकरा सकती हैं और फिर से login करने के लिए मजबूर कर सकती हैं।
Forward auth आपको क्या नहीं देता है
यह दरवाजे पर लगा एक गेट है। यह एप्लिकेशन के अंदर का ऑथराइजेशन (authorisation) नहीं है, और यही अंतर यह तय करता है कि यह तरीका आपके मामले के लिए उपयुक्त है या नहीं।
एक बार जब यूजर अंदर आ जाता है, तो एप्लिकेशन को वही दिखता है जो उसे हमेशा दिखता था। यदि एप्लिकेशन की अपनी भूमिकाएं (roles) हैं, तो forward auth उन्हें नहीं भरता, जब तक कि एप्लिकेशन header-based ऑथेंटिकेशन का समर्थन न करता हो और किसी हेडर को अकाउंट से मैप न करता हो। Grafana ऐसा करता है, इसके auth.proxy सेटिंग्स के माध्यम से। अधिकांश self-hosted एप्लिकेशन ऐसा नहीं करते हैं, इसलिए गेट से गुजरने वाला हर व्यक्ति एप्लिकेशन के लिए एक ही पहचान रखता है, और वह पहचान अक्सर एक एडमिन की होती है।
यह एप्लिकेशन के अपने API टोकन की भी सुरक्षा नहीं करता है। एप्लिकेशन द्वारा जारी किया गया एक पर्सनल एक्सेस टोकन एप्लिकेशन के लिए ऑथेंटिकेट करता है, न कि oauth2-proxy के लिए, इसलिए जैसे ही गेट इसके सामने आता है, टोकन काम करना बंद कर देता है। इसे वापस लाने के लिए API पाथ को छूट (exempt) दें और वह टोकन उस पाथ की सुरक्षा करने वाली एकमात्र चीज बन जाएगा। अब आप एक सर्विस पर दो ऑथेंटिकेशन सिस्टम चला रहे हैं, और SSO उनमें से केवल एक को कवर करता है।
Revocation तीसरी कमी है। अपने प्रोवाइडर में किसी यूजर को डिलीट करने से नए लॉगिन रुक जाते हैं, लेकिन oauth2-proxy तब तक प्रोवाइडर के साथ मौजूदा सेशन की जांच नहीं करता जब तक कि cookie_refresh का समय नहीं आ जाता। रिफ्रेश बंद होने पर, सेशन कुकी तब तक वैध रहती है जब तक कि वह समाप्त नहीं हो जाती, और cookie_expire डिफ़ॉल्ट रूप से 168 घंटे का होता है, जो किसी ऐसे व्यक्ति के लिए एक सप्ताह का एक्सेस हो सकता है जिसे आपने अभी-अभी हटाया है। cookie_refresh को एक घंटे जैसे कम समय पर सेट करें। जब प्रोवाइडर उस रिफ्रेश को अस्वीकार कर देता है क्योंकि यूजर का रिफ्रेश टोकन अब वैध नहीं है, तो oauth2-proxy सेशन को क्लियर कर देता है और रिफ्रेश का प्रयास करने वाले अगले अनुरोध पर नया लॉगिन करने के लिए मजबूर करता है। रिफ्रेश हर प्रोवाइडर द्वारा समर्थित नहीं है, इसलिए इसे अपने प्रोवाइडर के साथ टेस्ट करें।
ऑडिट ट्रेल भी गेट पर ही रुक जाता है। oauth2-proxy लॉग करता है कि कौन आया और कब आया। एप्लिकेशन एक अनाम (unnamed) सेशन को लॉग करता है। यदि आपको यह जवाब देना है कि सेटिंग किसने बदली, तो एप्लिकेशन में हेडर पहचान न्यूनतम आवश्यकता है, और वास्तविक प्रति-यूजर (per-user) अकाउंट ही सही समाधान है।
जब SSO टैक्स देना बेहतर विकल्प हो
Forward auth तब सही टूल है जब किसी ऐप में कोई लॉगिन न हो, या केवल एक साझा पासवर्ड हो, और आप लोगों को जोड़ने और हटाने के लिए एक ही स्थान चाहते हों। इसमें एक दोपहर का समय और एक अतिरिक्त प्रोसेस लगती है, और यह HTTP का समर्थन करने वाले किसी भी ऐप के साथ काम करता है।
यह तब गलत टूल है जब एक ही ऐप के भीतर अलग-अलग लोगों को अलग-अलग अनुमतियों की आवश्यकता होती है। एक गेट यह नहीं बता सकता कि "Ana डैशबोर्ड एडिट कर सकती है और Bo केवल उन्हें पढ़ सकता है"। यदि वेंडर SSO टियर बेचता है, तो आप वास्तव में ग्रुप-टू-रोल मैपिंग के लिए भुगतान कर रहे होते हैं, और इसे हेडर और प्रॉक्सी रूल्स के साथ फिर से बनाना, भुगतान करने की तुलना में अधिक नाजुक होता है। निर्णय लेने से पहले उन SSO टियर्स के पीछे का प्राइसिंग पैटर्न पढ़ना उचित है।
कोई भी ऐप जिसमें मोबाइल या डेस्कटॉप क्लाइंट है जो ब्राउज़र कुकीज़ का उपयोग नहीं करता है, वह हर रिक्वेस्ट पर गेट के साथ संघर्ष करेगा।
FAQ
Forward auth क्या है?
Forward auth एक ऐसा पैटर्न है जहाँ reverse proxy हर आने वाली request को upstream भेजने से पहले एक अलग authentication service से जाँचता है। Proxy request headers को /oauth2/auth जैसे endpoint पर भेजता है और status code पढ़ता है। 202 का अर्थ है अनुमति प्राप्त है, इसलिए मूल request application तक पहुँच जाती है। 401 का अर्थ है कोई वैध session नहीं है, इसलिए proxy browser को login page पर redirect कर देता है। Nginx इसे auth_request directive के साथ, Traefik forwardAuth middleware के साथ, और Caddy forward_auth के साथ लागू करता है।
oauth2-proxy मुझे login page पर बार-बार redirect क्यों करता है?
Session cookie गायब है या validation में विफल हो रही है, इसलिए हर जाँच में कोई वैध session नहीं मिलता और आपको वापस login पर भेज दिया जाता है। अलग-अलग cookie secrets का उपयोग करने वाले instances एक-दूसरे की cookies को अस्वीकार कर देते हैं। एक और कारण plain HTTP पर पहुँचने वाली साइट पर cookie_secure = true हो सकता है, क्योंकि localhost को छोड़कर, browser किसी http:// origin पर Secure cookie स्टोर नहीं करेगा। cookie_domains मान की भी जाँच करें जो address bar में मौजूद hostname को कवर नहीं करता हो। अपने browser के developer tools में /oauth2/callback response पर Set-Cookie header देखें ताकि पता चल सके कि कौन सी cookie गायब है। यदि cookie वापस आती है, तो validation errors के लिए server log देखें। यदि CSRF cookie गायब है, तो आपको लूप के बजाय Login Failed: Unable to find a valid CSRF token. Please try again. लिखा हुआ 403 page मिलता है, और जब कोई cookie नहीं पहुँचती तो log में No cookies were found in OAuth callback. दिखाई देता है।
मैं API client या webhook को oauth2-proxy से होकर कैसे जाने दूँ?
skip_auth_routes का उपयोग एक anchored regular expression के साथ करें, जिसे वैकल्पिक रूप से एक HTTP method तक सीमित किया जा सकता है, उदाहरण के लिए POST=^/webhook/, और v7.15.5 या उसके बाद का version चलाएँ, जिसने इन छूटों (exemptions) के एक गंभीर bypass को ठीक किया है। Method-specific छूटों के लिए आवश्यक है कि authentication request मूल method को सुरक्षित रखे; nginx और Caddy के उदाहरण GET checks करते हैं, इसलिए उन छूटों को reverse proxy की routing में संभालें। यदि आपके API clients के पास पहले से ही configured provider द्वारा जारी वैध JWTs हैं जिनका audience स्वीकार्य है, तो skip_jwt_bearer_tokens = true उन tokens को cookie के स्थान पर स्वीकार करता है और path को सुरक्षित रखता है। Audience को client_id या extra_jwt_issuers के माध्यम से configured audience से मेल खाना चाहिए। skip_auth_routes में सूचीबद्ध कोई भी चीज़ सभी के लिए unauthenticated है, इसलिए प्रत्येक expression को उतना ही सीमित रखें जितना caller अनुमति देता है।
क्या oauth2-proxy application को per-user permissions देता है?
नहीं। यह एक gate है, न कि कोई authorisation system। यह तय करता है कि application तक कौन पहुँचेगा, और जो भी वहाँ पहुँचता है वह application को एक जैसा ही दिखता है, जब तक कि वह application identity headers को न पढ़े और उन्हें accounts के साथ map न करे। Grafana अपने auth.proxy settings के माध्यम से ऐसा कर सकता है। अधिकांश self-hosted apps ऐसा नहीं कर सकतीं, इसलिए gate के पार जाने वाला हर व्यक्ति उसी identity को साझा करता है जिसके साथ app चल रही है।
क्या कोई खुद identity header सेट करके oauth2-proxy को bypass कर सकता है?
हाँ, यदि वे सीधे application तक पहुँच सकते हैं। Identity एक plain header जैसे X-Auth-Request-Email के रूप में आती है, और application उसे प्राप्त होने वाली हर चीज़ पर भरोसा करता है। जो कोई भी application port पर connection खोल सकता है, वह उस header को भेजकर कोई भी user बन सकता है। App को 127.0.0.1 पर bind करें, या इसे बिना किसी published port के internal Docker network पर रखें, और sudo ss -tlnp के साथ इसकी पुष्टि करें।