پیادهسازی SSO برای برنامهها با oauth2-proxy
با استفاده از قابلیت Forward Auth در oauth2-proxy، بدون تغییر در کد برنامه، احراز هویت OIDC را به Nginx یا Traefik اضافه کنید. از خطاهای رایج کوکی و ریدایرکت جلوگیری کنید.
احراز هویت پیشرو (Forward auth): چگونه یک برنامه بدون سیستم ورود، SSO دریافت میکند
ابزار oauth2-proxy برای برنامهای که سیستم ورود داخلی ندارد، قابلیت single sign-on فراهم میکند. این کار به این صورت انجام میشود که reverse proxy که در مقابل آن برنامه قرار دارد، تمامی درخواستها را متوقف میکند، از oauth2-proxy میپرسد که آیا درخواست دارای نشست (session) معتبر است یا خیر، و تنها زمانی درخواست را به سمت upstream هدایت میکند که پاسخ مثبت باشد. کد برنامه هرگز تغییر نمیکند، زیرا برنامه اصلاً متوجه این بررسی نمیشود.
این بررسی شامل یک درخواست HTTP اضافی است. پروکسی یک کپی از هدرهای درخواست ورودی را به /oauth2/auth ارسال کرده و کد وضعیت را میخواند. کد 202 به این معنی است که بررسی با موفقیت انجام شده، بنابراین پروکسی درخواست اصلی را به برنامه هدایت میکند. کد 401 به این معنی است که نشست معتبری وجود ندارد، بنابراین پروکسی مرورگر را به /oauth2/sign_in میفرستد که بهصورت پیشفرض یک صفحه ورود نمایش میدهد. /oauth2/start یک ورود OpenID Connect (OIDC) را در ارائهدهنده هویت شما آغاز میکند؛ skip_provider_button = true باعث میشود که /oauth2/sign_in این فرآیند را بهطور خودکار شروع کند. OIDC لایه هویتی است که بر پایه OAuth 2.0 ساخته شده و ارائهدهنده همان سرویسی است که هماکنون برای ورودها از آن استفاده میکنید.
این الگو در هر reverse proxy نام خاصی دارد. Nginx این دستورالعمل را auth_request مینامد. Traefik آن را middleware از نوع forwardAuth میخواند. Caddy آن را forward_auth مینامد. سرویسی که به این زیر-درخواست (sub-request) پاسخ میدهد نیز قابل جایگزینی است. oauth2-proxy انتخاب رایجی است زیرا از OIDC استاندارد پشتیبانی میکند و نیازی به دیتابیس اختصاصی ندارد.
پیش از نوشتن هرگونه پیکربندی، مرز اعتماد را ترسیم کنید
پس از بررسی موفقیتآمیز، oauth2-proxy هویت کاربر را در قالب هدرهای پاسخ بازمیگرداند و reverse 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: را از سرویس برنامه حذف کنید و آن را در شبکه داخلی باقی بگذارید تا فقط کانتینر پروکسی بتواند به آن متصل شود. روی یک میزبان خام (bare host)، برنامه را به جای 0.0.0.0:3000 به 127.0.0.1:3000 متصل (bind) کنید. سپس بررسی کنید که واقعاً چه چیزی را در معرض دید قرار دادهاید:
sudo ss -tlnp | grep 3000خطی که 0.0.0.0:3000 را نشان میدهد به این معنی است که برنامه روی IP عمومی پاسخ میدهد و دروازه شما صرفاً جنبه تزئینی دارد. 127.0.0.1:3000 همان چیزی است که باید به دنبال آن باشید. یک قانون فایروال لایه دوم مفیدی است، اما آدرس bind چیزی است که حتی پس از پاکسازی مجموعه قوانین توسط ابزارهای دیگر، همچنان باقی میماند.
نصب 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 secret
کوکی نشست (session cookie) رمزنگاریشده است و cookie_secret کلید آن محسوب میشود. طول این کلید رمزنگاری باید دقیقاً 16، 24 یا 32 بایت باشد، زیرا به عنوان یک کلید AES (استاندارد رمزنگاری پیشرفته) عمل میکند. برنامه oauth2-proxy یک مقدار base64 ایمن برای URL را میپذیرد که پس از رمزگشایی به یکی از این طولها برسد، یا یک secret خام با همین طولها را قبول میکند؛ در غیر این صورت، برنامه با خطای راهاندازی که به cookie secret اشاره دارد، اجرا نمیشود. دستور زیر یک مقدار 44 کاراکتری تولید میکند که یک کلید 32 بایتی را کدگذاری کرده است.
openssl rand -base64 32 | tr -- '+/' '-_'استفاده از tr صرفاً برای زیبایی نیست. این بخش، base64 استاندارد را به الفبای ایمن برای URL تبدیل میکند که oauth2-proxy هنگام رمزگشایی secret از آن استفاده میکند.
برای این مقدار دو قانون وجود دارد. برای هر deployment از یک secret متفاوت استفاده کنید. همچنین زمانی که بیش از یک نمونه oauth2-proxy را پشت یک دامنه واحد اجرا میکنید، به همه آنها secret یکسانی بدهید؛ زیرا کوکی رمزنگاریشده توسط یک نمونه، باید توسط سایر نمونهها نیز قابل خواندن باشد.
نوشتن پیکربندی 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 محدود میکند که کدام همتایان (peers) مجاز به ارسال این هدرها هستند. مقدار پیشفرض آن به همه منابع اعتماد میکند که در اینجا تنها به این دلیل امن است که 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 = ["*"] تمام آدرسهایی را که ارائهدهنده (provider) شما احراز هویت میکند، میپذیرد. آن را به دامنه خود محدود کنید، یا بهتر است دسترسی را با یک 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 به این معنی است که پردازش شروع شده و پیکربندی خود را بارگذاری کرده است. این endpoint سلامتِ خودِ oauth2-proxy است و هرگز درخواست نشست (session) نمیکند. اگر پاسخی دریافت نکردید، journalctl -u oauth2-proxy -n 50 را بخوانید، زیرا یک issuer URL اشتباه یا یک cookie secret با طول نادرست، هر دو باعث شکست در راهاندازی میشوند و هر دو مورد در لاگ ذکر میشوند.
ثبت URI تغییر مسیر (Redirect URI) نزد ارائهدهنده
یک برنامه OIDC در پنل ارائهدهنده خود ایجاد کنید و URI تغییر مسیر آن را دقیقاً برابر با redirect_url موجود در فایل پیکربندی قرار دهید: https://app.example.com/oauth2/callback. منظور از «دقیق»، تطابق کامل کاراکتر به کاراکتر در طرح (scheme)، میزبان (host)، پورت و مسیر است. وجود یک اسلش اضافه در انتهای آدرس، آن را به یک URI متفاوت تبدیل میکند.
این مورد رایجترین عامل شکست در کل فرآیند راهاندازی است و پیش از آنکه oauth2-proxy حتی درگیر شود، رخ میدهد. ارائهدهنده، درخواست احراز هویت را رد کرده و صفحه خطای اختصاصی خود را نمایش میدهد؛ بنابراین هیچ ردی در لاگهای oauth2-proxy ثبت نمیشود. نشانه این مشکل در نوار آدرس مرورگر مشخص است: مرورگر همچنان روی دامنه ارائهدهنده باقی مانده و رشته پرسوجو (query string) حاوی error=invalid_request است یا مستقیماً نام صفحات redirect_uri را نشان میدهد. در چنین شرایطی، رکورد برنامه را در پنل ارائهدهنده اصلاح کنید، نه در پیکربندی پروکسی.
URL صادرکننده (issuer URL) را بهجای تایپکردن، مستقیماً از ارائهدهنده کپی کنید. oauth2-proxy عبارت /.well-known/openid-configuration را به oidc_issuer_url اضافه کرده و سند discovery را در زمان شروع به کار فراخوانی میکند. ابتدا خودتان آن را بررسی کنید:
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 احراز هویت پیشدستانه (forward auth) را انجام میدهد؛ این دستور یک زیر-درخواست (sub-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 خالی، مانع از ارسال بدنه درخواست (request body) به نقطه پایانی احراز هویت میشود؛ چرا که آن نقطه پایانی تنها به هدرها نیاز دارد.
جفت دستورات auth_request_set $auth_cookie و add_header Set-Cookie، کوکی نشست (session cookie) تازهسازیشده را به مرورگر بازمیگردانند. اگر این بخش حذف شود، cookie_refresh بیسروصدا کاری انجام نمیدهد، زیرا Nginx هدرهای Set-Cookie مربوط به زیر-درخواست را نادیده میگیرد و مرورگر تا زمان انقضای نشست، مقدار قدیمی را حفظ میکند. این جفت دستور تنها یک کوکی را مدیریت میکنند؛ برای کوکیهای نشست چندبخشی، به مدیریت اضافی برای سایر بخشها یا استفاده از Redis برای ذخیرهسازی نشست نیاز است.
دستور error_page 401 = @oauth2_signin همان چیزی است که یک بررسی ناموفق را به صفحه ورود هدایت میکند. بدون این دستور، بازدیدکننده احراز هویتنشده با یک صفحه خالی 401 Authorization Required مواجه میشود و راهی برای ادامه نخواهد داشت.
همیشه پیش از بارگذاری مجدد (reload)، تنظیمات را تست کنید:
sudo nginx -t && sudo systemctl reload nginxاگر دستورالعملهای پیرامونی برای شما تازگی دارند، ساختار پیکربندی reverse proxy در Nginx لایه زیرین این تنظیمات را توضیح میدهد.
Traefik: میانافزار 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 اضافه کنید. بدون این بازنویسی (rewrite)، 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 است، زیرا کاربری که وارد سیستم نشده است باید بتواند به مسیرهای ورود (sign-in) و callback دسترسی داشته باشد. اگر بررسی را پیش از این مسیرها قرار دهید، فرآیند ورود تا زمانی که مرورگر از ادامه کار منصرف شود، بهصورت حلقهای به خودش redirect خواهد شد.
copy_headers همان چیزی است که هویت کاربر را به درخواست upstream منتقل میکند و تنها زمانی مقادیر را تولید میکند که oauth2-proxy با set_xauthrequest = true اجرا شده باشد. انتخاب بین پروکسیهای مختلف موضوعی جداگانه است و مقایسه Nginx، Caddy و Traefik به بررسی آن میپردازد.
چرا ورود به سیستم به صفحه ورود بازمیگردد؟
شما در سرویسدهنده احراز هویت وارد میشوید، آن سرویس شما را بازمیگرداند و oauth2-proxy دوباره شما را به صفحه ورود میفرستد. این حلقه به این معناست که oauth2-proxy در درخواست بعدی، نشست (session) معتبر را نمیپذیرد. کوکی نشست ممکن است وجود نداشته باشد، یا وجود داشته باشد اما در اعتبارسنجی شکست بخورد؛ برای مثال زمانی که نمونههای مختلف از cookie secretهای متفاوتی استفاده میکنند. ابزارهای توسعهدهنده مرورگر را باز کنید، درخواست به /oauth2/callback را که پس از بازگشت از سرویسدهنده ارسال میشود پیدا کنید و هدر پاسخ Set-Cookie آن را بخوانید. کوکیای که در آنجا تنظیم شده اما در درخواست بعدی وجود ندارد، همان کوکی است که مرورگر از پذیرش آن خودداری میکند. اگر کوکی وجود دارد، لاگ سرور را برای خطاهای اعتبارسنجی مانند cookie signature not valid بررسی کنید و مطمئن شوید که همه نمونهها از secret یکسانی استفاده میکنند.
زمانی که کوکی گمشده، کوکی CSRF باشد که oauth2-proxy در مسیر خروج تنظیم کرده است، جریان کار وارد حلقه نمیشود. فرآیند در callback متوقف شده و لاگ علت را مشخص میکند:
No cookies were found in OAuth callback.یا زمانی که کوکیهای دیگر ارسال شدهاند اما کوکی صحیح ارسال نشده است:
Cookies were found in OAuth callback, but none was a CSRF cookie.CSRF مخفف جعل درخواست میانسایتی (cross-site request forgery) است و این کوکی وجود دارد تا callback بتواند به ورود به سیستمی که آن را آغاز کرده متصل شود. مرورگر یک صفحه خطای 403 دریافت میکند که شامل این پیام است:
Login Failed: Unable to find a valid CSRF token. Please try again.کوکیهای گمشده سه علت اول زیر را به اشتراک میگذارند؛ اختلاف ساعت (clock drift) علت دیگری برای شکست اعتبارسنجی است. این چهار مورد را به ترتیب بررسی کنید.
cookie_secure = trueدر حالی که مرورگر از طریق HTTP ساده به سایت رسیده است. به جز در localhost، مرورگر کوکی علامتگذاریشده باSecureرا روی مبدأhttp://ذخیره نمیکند، بنابراین هرگز بازگردانده نمیشود. TLS (امنیت لایه انتقال) را بهدرستی terminate کنید، یاcookie_secure = falseرا فقط هنگام تست روی localhost تنظیم کنید.- مقدار
cookie_domainsکه نام میزبان (hostname) موجود در نوار آدرس را پوشش نمیدهد..example.comشاملapp.example.comمیشود و هیچ تأثیری رویapp.example.netندارد. - مرورگر کوکی را حذف میکند. یک افزونه حریم خصوصی سختگیرانه یا مسدودکننده کوکیهای شخص ثالث میتواند
_oauth2_proxy_csrfرا بین redirect خروجی و callback، یا کوکی نشست را پس از آن حذف کند. - اختلاف ساعت. اگر ساعت سرور بسیار جلوتر از ساعت سرویسدهنده باشد، توکن ID ممکن است منقضیشده به نظر برسد و در اعتبارسنجی شکست بخورد.
timedatectlبایدSystem clock synchronized: yesرا گزارش دهد.
یک علت دیگر نیز وجود دارد که بدون هیچ پیکربندی اشتباهی، خطای CSRF ایجاد میکند. بهصورت پیشفرض، oauth2-proxy یک کوکی CSRF واحد نگه میدارد، بنابراین دو تب که همزمان ورود به سیستم را شروع میکنند، کوکیهای یکدیگر را بازنویسی میکنند. cookie_csrf_per_request = true به هر ورود به سیستم، کوکی اختصاصی خود را میدهد.
بهجای حدس زدن، وقوع آن را از سمت سرور مشاهده کنید:
sudo journalctl -u oauth2-proxy -fبرنامه را در یک پنجره خصوصی (private window) بارگذاری کنید. هر درخواست با وضعیت خود لاگ میشود، بنابراین یک callback که بلافاصله با یک redirect دیگر به صفحه ورود دنبال میشود، همان حلقه است که در لاگ ثبت شده است.
مسیرهایی که باید از ورود اجباری عبور کنند: APIها، وبهوکها و وبسوکتها
احراز هویت پیشرو (Forward auth) فرض را بر این میگذارد که مرورگر دارای کوکی است. کلاینتهایی که مرورگر ندارند، در این حالت دچار مشکل میشوند.
یک کلاینت API که Authorization: Bearer <token> ارسال میکند، کوکی ندارد؛ بنابراین پیکربندیهای پروکسی که در بالا ذکر شد، آن را به صفحه ورود oauth2-proxy هدایت میکند، مگر اینکه احراز هویت با bearer-token فعال باشد. دو راه حل تمیز برای این مسئله وجود دارد. تنظیم skip_jwt_bearer_tokens = true باعث میشود oauth2-proxy یک bearer token معتبر از نوع JWT (JSON web token) را از صادرکننده پیکربندیشده و با مخاطب (audience) پذیرفتهشده برای این کلاینت بپذیرد؛ این روش زمانی مناسب است که کلاینتهای API شما از قبل توکنهای مناسب را از ارائهدهنده دریافت کرده باشند. مقدار aud در توکن باید با client_id یا مخاطبی که از طریق extra_jwt_issuers پیکربندی شده است، مطابقت داشته باشد. در غیر این صورت، مسیر را مستثنی کنید:
skip_auth_routes = [
"^/api/",
"POST=^/webhook/",
"GET=^/healthz$"
]هر مقدار، یک عبارت منظم (regular expression) است که با مسیر رمزگشاییشده (بدون پارامترهای پرسوجو) مطابقت داده میشود و میتواند بهصورت اختیاری با یک متد HTTP و = پیشوند شود. POST=^/webhook/ باعث میشود گیرنده وبهوک برای متد POST باز بماند، در حالی که کاربر انسانی که به همان مسیر مراجعه میکند همچنان به صفحه ورود هدایت میشود، مشروط بر اینکه درخواست احراز هویت، متد اصلی را حفظ کند. دستورات auth_request در Nginx و forward_auth در Caddy بررسیهای GET انجام میدهند، بنابراین در آن تنظیمات، استثناهای خاصِ متد نیاز به مسیریابی جداگانه در reverse proxy دارند. هر ورودی، حفرهای در دروازه امنیتی شماست؛ بنابراین عبارتها را با ^ محدود کنید و آنها را تا حد امکان دقیق و محدود نگه دارید.
پیش از تکیه بر این قابلیتها، از نسخه v7.15.5 یا بالاتر استفاده کنید. نسخههای پس از v7.5.0 تا پیش از v7.15.5 ممکن بود با درخواستی که شامل dot segmentها، اسلش دوتایی در ابتدا یا سمیکولون بود، فریب خورده و یک مسیر محافظتشده را مستثنی کنند (اخطار امنیتی GHSA-63jm-59jj-478j)؛ در آن نسخهها، محدود کردن عبارتها نیز مانع این اتفاق نمیشد. نسخه اصلاحشده از مستثنی کردن چنین مسیرهای مبهمی خودداری میکند، بنابراین پس از ارتقا بررسی کنید که مسیرهای عمومی شما همچنان بهدرستی مطابقت داده میشوند.
وبسوکتها موردی هستند که افراد در آن دچار اشتباه میشوند. درخواست ارتقا (upgrade request) یک درخواست HTTP GET معمولی است که همان کوکیهای سایر درخواستها را حمل میکند، بنابراین بهطور عادی از بررسی عبور میکند و نیازی به استثنا ندارد. آنچه باعث خرابی میشود، پروکسی کردن پیرامون آن است. بدون هدرهای Upgrade و Connection در location محافظتشده، ارتقا هرگز تکمیل نمیشود و کلاینت برنامه بهطور مداوم با پیام WebSocket connection ... failed در کنسول مرورگر تلاش مجدد میکند. مستثنی کردن مسیر در اینجا هیچ مشکلی را حل نمیکند، زیرا درخواست از قبل احراز هویت شده است.
یک محدودیت واقعی وجود دارد. بررسی فقط یکبار و در زمان ارتقا انجام میشود. وبسوکتی که ساعتها باز میماند، دیگر بازبینی نمیشود؛ بنابراین حذف یک کاربر از ارائهدهنده، سوکتی را که در حال حاضر در اختیار دارد نمیبندد. برای قطع اتصالات فعال، برنامه را مجدداً راهاندازی کنید.
ذخیرهسازی نشست و کوکیهایی که بیش از حد بزرگ میشوند
بهصورت پیشفرض، کل نشست درون کوکی قرار میگیرد و با cookie_secret رمزنگاری میشود. این کار باعث میشود oauth2-proxy بدون وضعیت (stateless) باقی بماند و به سرویس اضافی نیاز نداشته باشد. با این حال، این روش محدودیتی دارد، زیرا مرورگرها ظرفیت کوکی را در حدود 4 KB محدود میکنند. هنگامی که ID token شامل لیست طولانی از ادعاهای گروه (group 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 نمیتواند نشستها را بارگذاری کند؛ از دست رفتن دادههای نشست ذخیرهشده باعث میشود همه کاربران مجبور به ورود مجدد شوند. ذخیرهسازی در کوکی نیز هزینه خاص خود را دارد؛ به این صورت که دو درخواست که همزمان سعی در تازهسازی یک نشست دارند، ممکن است با هم تداخل پیدا کرده و کاربر را مجبور به ورود مجدد کنند.
مواردی که forward auth برای شما فراهم نمیکند
این مکانیزم مانند یک دروازه در ورودی عمل میکند. این ابزار جایگزین احراز هویت (authorisation) در داخل خودِ برنامه نیست و همین تفاوت تعیین میکند که آیا این روش برای مورد استفاده شما مناسب است یا خیر.
هنگامی که کاربر از دروازه عبور میکند، برنامه همان چیزی را میبیند که همیشه میدیده است. اگر برنامه دارای نقشهای (roles) داخلی خود باشد، forward auth آنها را پر نمیکند، مگر اینکه برنامه از احراز هویت مبتنی بر هدر (header-based authentication) پشتیبانی کند و یک هدر را به یک حساب کاربری نگاشت (map) نماید. Grafana این کار را از طریق تنظیمات auth.proxy انجام میدهد. اکثر برنامههای self-hosted چنین قابلیتی ندارند، بنابراین هر کسی که از دروازه عبور میکند، برای برنامه یک هویت واحد و یکسان محسوب میشود و این هویت اغلب نقش مدیر (admin) را دارد.
این روش همچنین از API tokenهای خودِ برنامه محافظت نمیکند. یک توکن دسترسی شخصی (personal access token) که توسط برنامه صادر شده است، برای احراز هویت در خودِ برنامه معتبر است، نه در oauth2-proxy؛ بنابراین به محض اینکه دروازه را جلوی آن قرار دهید، توکن از کار میافتد. اگر مسیر API را از این محدودیت مستثنی (exempt) کنید تا دوباره کار کند، آن توکن به تنها عامل محافظتکننده از آن مسیر تبدیل میشود. در این حالت شما دو سیستم احراز هویت متفاوت را روی یک سرویس اجرا میکنید و SSO تنها یکی از آنها را پوشش میدهد.
ابطال دسترسی (revocation) سومین شکاف امنیتی است. حذف یک کاربر در سرویسدهنده (provider) شما، از ورودهای جدید جلوگیری میکند، اما oauth2-proxy تا زمانی که زمان cookie_refresh فرا نرسد، نشست (session) موجود را با سرویسدهنده بررسی نمیکند. اگر قابلیت refresh غیرفعال باشد، کوکی نشست تا زمان انقضا معتبر باقی میماند و مقدار پیشفرض cookie_expire برابر با 168 ساعت است که میتواند به معنای یک هفته دسترسی برای کسی باشد که شما بهتازگی دسترسیاش را حذف کردهاید. مقدار cookie_refresh را روی بازه کوتاهی مانند یک ساعت تنظیم کنید. هنگامی که سرویسدهنده آن درخواست refresh را به دلیل نامعتبر بودن توکنِ کاربر رد کند، oauth2-proxy نشست را پاک کرده و در درخواست بعدی که سعی در refresh دارد، کاربر را مجبور به ورود مجدد میکند. قابلیت refresh توسط همه سرویسدهندهها پشتیبانی نمیشود، بنابراین آن را با سرویسدهنده خود تست کنید.
ردپای حسابرسی (audit trail) نیز در همان دروازه متوقف میشود. oauth2-proxy ثبت میکند که چه کسی و چه زمانی عبور کرده است، اما برنامه یک نشست بدون نام را ثبت میکند. اگر مجبور هستید پاسخ دهید که چه کسی تنظیمی را تغییر داده است، هویت مبتنی بر هدر در برنامه حداقلِ نیاز است و حسابهای کاربری واقعی برای هر شخص، پاسخ دقیق و صحیح محسوب میشود.
چه زمانی پرداخت هزینه SSO انتخاب بهتری است
Forward auth ابزار مناسبی است زمانی که یک برنامه اصلاً سیستم ورود ندارد، یا از یک رمز عبور مشترک استفاده میکند و شما میخواهید یک نقطه واحد برای افزودن و حذف کاربران داشته باشید. این کار به اندازه یک بعدازظهر زمان و یک پردازش اضافی هزینه دارد و با هر برنامهای که از پروتکل HTTP پشتیبانی میکند، کار میکند.
این ابزار انتخاب اشتباهی است زمانی که افراد مختلف به سطوح دسترسی متفاوتی در داخل همان برنامه نیاز دارند. یک دروازه (gate) نمیتواند شرطی مانند «آنا میتواند داشبوردها را ویرایش کند و بو فقط میتواند آنها را بخواند» را اعمال کند. اگر فروشنده یک نسخه SSO ارائه میدهد، نگاشت گروه به نقش (group-to-role mapping) معمولاً همان چیزی است که در واقع بابت آن هزینه پرداخت میکنید؛ بازسازی این قابلیت با استفاده از هدرها و قوانین پروکسی، شکنندهتر از خرید آن است. مطالعه الگوی قیمتگذاری پشت آن نسخههای SSO پیش از تصمیمگیری در هر دو حالت، ارزشمند است.
هر برنامهای که کلاینت موبایل یا دسکتاپ دارد و از کوکیهای مرورگر استفاده نمیکند، در هر درخواست با این دروازه دچار مشکل خواهد شد.
FAQ
احراز هویت پیشرو (forward auth) چیست؟
احراز هویت پیشرو الگویی است که در آن reverse proxy پیش از ارسال هر درخواست ورودی به مقصد اصلی، از یک سرویس احراز هویت جداگانه استعلام میگیرد. پروکسی هدرهای درخواست را به یک endpoint مانند /oauth2/auth ارسال کرده و کد وضعیت را میخواند. کد 202 به معنای مجاز بودن است، بنابراین درخواست اصلی به سمت برنامه هدایت میشود. کد 401 به معنای نبود نشست (session) معتبر است، در نتیجه پروکسی مرورگر را به صفحه ورود هدایت میکند. Nginx این قابلیت را با دستور auth_request، Traefik با میانافزار (middleware) forwardAuth و Caddy با forward_auth پیادهسازی میکنند.
چرا oauth2-proxy مرا در یک حلقه به صفحه ورود بازمیگرداند؟
کوکی نشست (session cookie) وجود ندارد یا اعتبارسنجی آن با شکست مواجه میشود؛ بنابراین در هر بررسی، نشست معتبری یافت نشده و شما به صفحه ورود هدایت میشوید. نمونههایی که از cookie secretهای متفاوت استفاده میکنند، کوکیهای یکدیگر را رد میکنند. دلیل دیگر، استفاده از cookie_secure = true در سایتی است که مرورگر از طریق HTTP ساده به آن دسترسی پیدا کرده است؛ زیرا مرورگرها به جز در localhost، کوکی Secure را روی مبدأ http:// ذخیره نمیکنند. همچنین مقدار cookie_domains را بررسی کنید که آیا نام میزبان (hostname) موجود در نوار آدرس را پوشش میدهد یا خیر. هدر Set-Cookie را در پاسخ /oauth2/callback در ابزارهای توسعهدهنده مرورگر خود بخوانید تا متوجه شوید کدام کوکی حذف شده است. اگر کوکی بازگردانده میشود، لاگ سرور را برای خطاهای اعتبارسنجی بررسی کنید. اگر کوکی CSRF حذف شده باشد، به جای حلقه، با یک صفحه 403 حاوی متن Login Failed: Unable to find a valid CSRF token. Please try again. مواجه میشوید و در صورت عدم دریافت کوکی، لاگ عبارت No cookies were found in OAuth callback. را نشان میدهد.
چگونه به یک کلاینت API یا webhook اجازه عبور از oauth2-proxy را بدهم؟
از skip_auth_routes با یک عبارت منظم (regular expression) محدودشده استفاده کنید که در صورت تمایل میتواند به یک متد HTTP خاص محدود شود؛ برای مثال POST=^/webhook/. از نسخه 7.15.5 یا بالاتر استفاده کنید که یک حفره امنیتی مهم در این معافیتها را برطرف کرده است. معافیتهای مختص به متد، نیازمند این هستند که درخواست احراز هویت، متد اصلی را حفظ کند؛ نمونههای nginx و Caddy بررسیهای GET انجام میدهند، بنابراین این معافیتها را در مسیریابی (routing) reverse proxy مدیریت کنید. اگر کلاینتهای API شما از قبل دارای JWTهای معتبری هستند که توسط ارائهدهنده پیکربندیشده و با audience پذیرفتهشده صادر شدهاند، skip_jwt_bearer_tokens = true این توکنها را به جای کوکی میپذیرد و مسیر را محافظتشده نگه میدارد. مقدار audience باید با client_id یا audience پیکربندیشده از طریق extra_jwt_issuers مطابقت داشته باشد. هر چیزی که در skip_auth_routes لیست شده باشد برای همه بدون احراز هویت در دسترس است، بنابراین هر عبارت را تا حد امکان محدود نگه دارید.
آیا oauth2-proxy مجوزهای کاربری (per-user permissions) را به برنامه میدهد؟
خیر. این یک دروازه است، نه یک سیستم مجوزدهی. این ابزار تصمیم میگیرد چه کسی به برنامه دسترسی پیدا کند، و برای برنامه، تمام کسانی که از دروازه عبور میکنند یکسان به نظر میرسند، مگر اینکه آن برنامه هدرهای هویت را بخواند و آنها را به حسابهای کاربری نگاشت کند. Grafana میتواند این کار را از طریق تنظیمات auth.proxy انجام دهد. اکثر برنامههای self-hosted قادر به این کار نیستند، بنابراین هر شخصی که از دروازه عبور میکند، از همان هویت واحدی استفاده میکند که برنامه با آن در حال اجراست.
آیا کسی میتواند با تنظیم دستی هدر هویت، oauth2-proxy را دور بزند؟
بله، اگر بتواند مستقیماً به برنامه دسترسی پیدا کند. هویت به صورت یک هدر ساده مانند X-Auth-Request-Email ارسال میشود و برنامه به هر چیزی که دریافت کند اعتماد میکند. هر کسی که بتواند اتصالی به پورت برنامه برقرار کند، میتواند آن هدر را ارسال کرده و خود را به عنوان هر کاربری جا بزند. برنامه را روی 127.0.0.1 محدود کنید یا آن را در یک شبکه داخلی Docker بدون پورت منتشرشده نگه دارید و با دستور sudo ss -tlnp آن را تأیید کنید.