SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-11-06

كيف تضيف SSO إلى أي تطبيق باستخدام oauth2-proxy

تعلّم حماية تطبيق بلا تسجيل دخول عبر OIDC وoauth2-proxy مع Nginx أو Traefik. افهم معنى 202 و401 وتجنّب أخطاء ملفات تعريف الارتباط وإعادة التوجيه.

المصادقة الأمامية (Forward auth): كيف تحصل التطبيقات التي تفتقر إلى تسجيل دخول على ميزة SSO

يُوفّر oauth2-proxy ميزة تسجيل الدخول الموحد (SSO) للتطبيقات التي لا تملك نظام تسجيل دخول خاص بها. تعمل هذه الآلية لأن الوكيل العكسي (reverse proxy) الموجود أمام التطبيق يعترض كل طلب، ويسأل oauth2-proxy عما إذا كان الطلب يحمل جلسة صالحة، ثم يمرر الطلب إلى التطبيق فقط عندما تكون الإجابة بالإيجاب. لا يتغير كود التطبيق أبداً، لأن التطبيق لا يرى عملية التحقق هذه.

عملية التحقق هي مجرد طلب HTTP إضافي. يرسل الوكيل نسخة من ترويسات الطلب الوارد إلى /oauth2/auth ويقرأ رمز الحالة. يعني الرمز 202 أن التحقق قد تم بنجاح، لذا يمرر الوكيل الطلب الأصلي إلى التطبيق. أما الرمز 401 فيعني عدم وجود جلسة صالحة، لذا يوجه الوكيل المتصفح إلى /oauth2/sign_in، الذي يعرض صفحة تسجيل دخول افتراضية. يبدأ /oauth2/start عملية تسجيل دخول عبر OpenID Connect (OIDC) لدى مزود الهوية الخاص بك؛ بينما يجعل skip_provider_button = true من /oauth2/sign_in يبدأها تلقائياً. OIDC هو طبقة الهوية المبنية فوق OAuth 2.0، والمزود هو أي نظام تستخدمه بالفعل لتسجيل الدخول.

لهذا النمط اسم في كل وكيل عكسي. يسمي Nginx التوجيه auth_request. ويسمي Traefik الوسيط (middleware) باسم forwardAuth. بينما يكتبه Caddy بصيغة forward_auth. الخدمة التي تجيب على الطلب الفرعي قابلة للاستبدال أيضاً. يُعد oauth2-proxy الخيار الشائع لأنه يدعم OIDC القياسي ولا يحتاج إلى قاعدة بيانات خاصة به.

ارسم حدود الثقة قبل كتابة أي إعدادات

بعد التحقق الناجح، يُعيد oauth2-proxy هوية المستخدم في ترويسات الاستجابة (response headers)، ويقوم الـ reverse proxy بنسخها إلى الطلب الموجه نحو التطبيق (upstream request). عند تفعيل 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/ واحد يعتبر تجاوزاً كاملاً للأمان إذا وصل الطلب إلى التطبيق مباشرة.

لذا، يجب ألا يكون التطبيق قابلاً للوصول إلا من خلال الـ proxy. في Docker Compose، احذف تعيين ports: من خدمة التطبيق واتركه على الشبكة الداخلية فقط، بحيث لا يمكن سوى لحاوية الـ proxy الاتصال به. على خادم فعلي (bare host)، اربط التطبيق بـ 127.0.0.1:3000 بدلاً من 0.0.0.0:3000. ثم تحقق مما قمت بكشفه فعلياً:

sudo ss -tlnp | grep 3000

السطر الذي يقرأ 0.0.0.0:3000 يعني أن التطبيق يستجيب على عنوان IP عام وأن بوابتك مجرد ديكور. 127.0.0.1:3000 هو ما تريده. تُعد قاعدة جدار الحماية طبقة ثانية مفيدة، لكن عنوان الربط (bind address) هو الذي يصمد في حال قيام أداة أخرى بمسح مجموعة قواعدك.

تثبيت 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 --version

يجب أن يطبع sha256sum -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 هو المفتاح المستخدم لذلك. يجب أن يكون طول مفتاح التشفير 16 أو 24 أو 32 بايت بالضبط، لأنه سيُستخدم كمفتاح AES (معيار التشفير المتقدم). يقبل oauth2-proxy قيمة base64 آمنة للاستخدام في الروابط (URL-safe) والتي تُفك شيفرتها لتصل إلى أحد هذه الأطوال، أو يقبل سراً خاماً بنفس الأطوال؛ وإلا فإنه سيرفض البدء، مع ظهور خطأ عند التشغيل يشير إلى سر ملف تعريف الارتباط. يُنتج الأمر أدناه قيمة مكونة من 44 حرفاً تُمثّل مفتاحاً بطول 32 بايت.

openssl rand -base64 32 | tr -- '+/' '-_'

إن استخدام tr ليس أمراً تجميلياً. فهو يحوّل base64 القياسي إلى الأبجدية الآمنة للاستخدام في الروابط التي يعتمدها oauth2-proxy عند فك شيفرة السر.

هناك قاعدتان لهذه القيمة. استخدم سراً مختلفاً لكل عملية نشر. وعند تشغيل أكثر من مثيل (instance) لـ oauth2-proxy خلف النطاق نفسه، امنحهم جميعاً السر ذاته، لأن ملف تعريف الارتباط الذي يتم تشفيره بواسطة مثيل واحد يجب أن يكون قابلاً للقراءة من قِبل المثيلات الأخرى.

اكتب إعدادات oauth2-proxy

احتفظ بالإعدادات في ملف بدلاً من استخدام سطر أوامر طويل، حتى لا يظهر سر العميل في مخرجات 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-* الواردة من الـproxy الموجود أمامه. من دون هذا الإعداد، يتعامل oauth2-proxy مع عنوان الـproxy نفسه على أنه عنوان العميل، وقد يحدد بشكل خاطئ ما إذا كان الطلب قد وصل عبر HTTPS.

يحدّد trusted_proxy_ips الأقران الذين يمكنهم إرسال هذه الرؤوس. القيمة الافتراضية تثق في كل مصدر، وهذا آمن هنا فقط لأن http_address يُبقي oauth2-proxy مستمعاً على 127.0.0.1. عندما يستمع oauth2-proxy على شبكة Docker، اضبطه على عنوان الـreverse proxy.

يجعل upstreams = ["static://202"] ‏oauth2-proxy يعيد الحالة 202 للطلب المصادق عليه من دون تمرير أي شيء، وهذا هو المطلوب تماماً في forward auth، لأن الـreverse proxy يتولى تمرير الطلب. يضع شكل النشر الآخر oauth2-proxy مباشرة في مسار الطلب باستخدام upstreams = ["http://127.0.0.1:3000"] ومن دون auth_request إطلاقاً. هذا أبسط لتطبيق واحد، لكنه لا يتوسع إلى عشرة تطبيقات.

يسمح email_domains = ["*"] بكل عنوان سيجري موفّر الهوية مصادقته. قلّصه إلى نطاقك الخاص، أو الأفضل من ذلك، قيّد الوصول من خلال ربط مجموعة في موفّر الهوية، لأنك تدير المستخدمين هناك بالفعل.

شغّله عبر systemd باستخدام مستخدم مستقل:

# /etc/systemd/system/oauth2-proxy.service
[Unit]
Description=oauth2-proxy
After=network-online.target
Wants=network-online.target

[Service]
User=oauth2-proxy
Group=oauth2-proxy
ExecStart=/usr/local/bin/oauth2-proxy --config=/etc/oauth2-proxy/oauth2-proxy.cfg
Restart=on-failure
ProtectSystem=strict
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
sudo 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

تعني طباعة OK عبر /ping أن العملية بدأت وحمّلت إعداداتها. هذه هي نقطة الصحة الخاصة بـoauth2-proxy، ولا تطلب جلسة مطلقاً. إذا لم يستجب أي شيء، اقرأ journalctl -u oauth2-proxy -n 50، لأن عنوان issuer غير الصحيح وسر ملفات تعريف الارتباط ذي الطول الخاطئ يفشلان معاً عند بدء التشغيل، ويذكر السجل ذلك في الحالتين.

تسجيل رابط إعادة التوجيه (Redirect URI) لدى مزود الخدمة

أنشئ تطبيق OIDC لدى مزود الخدمة واضبط رابط إعادة التوجيه الخاص به ليكون مطابقاً تماماً لـ redirect_url الموجود في ملف الإعداد: https://app.example.com/oauth2/callback. المطابقة التامة تعني أن البروتوكول (scheme) والمضيف (host) والمنفذ (port) والمسار (path) يجب أن تتطابق حرفياً. وجود شرطة مائلة إضافية في النهاية يجعل الرابط مختلفاً.

هذا هو سبب الفشل الأكثر شيوعاً في عملية الإعداد بأكملها، ويحدث الفشل قبل أن يبدأ oauth2-proxy في العمل. يرفض مزود الخدمة طلب التفويض ويعرض صفحة الخطأ الخاصة به، لذا لن يظهر أي شيء في سجلات oauth2-proxy. العلامة الدالة على ذلك تظهر في شريط العنوان: المتصفح لا يزال على نطاق مزود الخدمة، وسلسلة الاستعلام (query string) تحمل error=invalid_request أو أسماء الصفحات redirect_uri مباشرة. عندما ترى ذلك، قم بتصحيح سجل التطبيق لدى مزود الخدمة، وليس في إعدادات البروكسي.

انسخ رابط جهة الإصدار (issuer URL) من مزود الخدمة بدلاً من كتابته يدوياً. يقوم oauth2-proxy بإلحاق /.well-known/openid-configuration بـ oidc_issuer_url ويجلب مستند الاكتشاف (discovery document) عند بدء التشغيل. تحقق منه بنفسك أولاً:

curl -s https://id.example.com/application/o/myapp/.well-known/openid-configuration | head -c 400

وجود ملف JSON يحتوي على مفتاح authorization_endpoint هو الخطوة الأولى للتحقق؛ كما يجب أن يتطابق issuer الموجود في المستند تماماً مع oidc_issuer_url. ظهور خطأ 404 أو صفحة خطأ بتنسيق HTML يعني أن الرابط غير صحيح، وسيفشل oauth2-proxy في البدء بسبب نفس الخطأ 404. إذا لم تختر مزود خدمة بعد، فإن مقارنة Keycloak وAuthentik وZitadel تغطي المفاضلات بينها، ويشرح تشغيل Authentik كخادم SSO خاص بك خطوات إعداد جانب مزود الخدمة لهذا الإعداد بالتحديد.

Nginx: auth_request

يُجري Nginx المصادقة الموجهة (forward auth) باستخدام auth_request، والذي يُطلق طلبًا فرعيًا داخليًا ويتفرع بناءً على رمز الحالة الخاص به.

# in the http context, next to your other maps
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 443 ssl;
  server_name app.example.com;

  location /oauth2/ {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host                    $host;
    proxy_set_header X-Real-IP               $remote_addr;
    proxy_set_header X-Auth-Request-Redirect $request_uri;
  }

  location = /oauth2/auth {
    proxy_pass       http://127.0.0.1:4180;
    proxy_set_header Host             $host;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-Uri  $request_uri;
    proxy_set_header Content-Length   "";
    proxy_pass_request_body           off;
  }

  location / {
    auth_request /oauth2/auth;
    error_page 401 = @oauth2_signin;

    auth_request_set $user  $upstream_http_x_auth_request_user;
    auth_request_set $email $upstream_http_x_auth_request_email;
    proxy_set_header X-User  $user;
    proxy_set_header X-Email $email;

    auth_request_set $auth_cookie $upstream_http_set_cookie;
    add_header Set-Cookie $auth_cookie;

    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host       $host;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
  }

  location @oauth2_signin {
    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
  }
}

هناك ثلاث تفاصيل في هذا الإعداد تستحق الذكر. يمنع proxy_pass_request_body off مع قيمة Content-Length فارغة Nginx من تمرير نص الطلب (request body) إلى نقطة نهاية المصادقة، والتي لا تحتاج سوى إلى الترويسات (headers).

يقوم الزوج 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 فارغة دون أي وسيلة للمتابعة.

اختبر الإعدادات قبل إعادة التحميل، دائماً:

sudo nginx -t && sudo systemctl reload nginx

إذا كانت التوجيهات المحيطة جديدة عليك، فإن تشريح إعدادات Nginx Reverse Proxy يغطي الطبقة الأساسية التي تقع تحت هذا الإعداد.

Traefik: وسيط forwardAuth

يحتاج Traefik إلى وسيطين (middlewares) لأداء المهمة نفسها. يقوم الأول بإجراء التحقق، بينما يخدم الثاني صفحة تسجيل الدخول عند فشل التحقق.

# 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) الذي يخدم تطبيقك، مع وضع 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 المضيف والمسار الأصليين إلى 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، لأن الزائر الذي لم يسجل دخوله يجب أن يتمكن من الوصول إلى مسارات تسجيل الدخول والاستدعاء (callback). إذا وضعت التحقق قبل هذه المسارات، فسيؤدي ذلك إلى إعادة توجيه تسجيل الدخول إلى نفسه حتى يتوقف المتصفح عن المحاولة.

copy_headers هي المسؤولة عن نقل هوية المستخدم إلى الطلب الموجه (upstream request)، وهي لا تنتج قيماً إلا عند تشغيل oauth2-proxy باستخدام set_xauthrequest = true. الاختيار بين الوكلاء (proxies) هو مسألة مستقلة، ومقارنة nginx وCaddy وTraefik توضح ذلك بالتفصيل.

لماذا تعود عملية تسجيل الدخول إلى صفحة تسجيل الدخول مجدداً؟

أنت تسجل الدخول لدى المزوّد، ثم يعيد توجيهك، ليقوم oauth2-proxy بإعادتك إلى صفحة تسجيل الدخول. تعني هذه الحلقة أن oauth2-proxy لا يقبل جلسة صالحة في الطلب التالي. قد يكون ملف تعريف الارتباط (cookie) الخاص بالجلسة مفقوداً، أو موجوداً ولكنه يفشل في التحقق، على سبيل المثال عندما تستخدم المثيلات أسراراً مختلفة لملفات تعريف الارتباط. افتح أدوات المطور في المتصفح، وابحث عن الطلب الموجه إلى /oauth2/callback الذي يلي إعادة التوجيه من المزوّد، واقرأ ترويسة الاستجابة Set-Cookie. ملف تعريف الارتباط الذي يتم تعيينه هناك ويختفي في الطلب التالي هو الذي يرفضه المتصفح. إذا كان موجوداً، تحقق من سجل الخادم بحثاً عن أخطاء التحقق مثل cookie signature not valid وتأكد من أن جميع المثيلات تستخدم نفس السر.

عندما يكون ملف تعريف الارتباط المفقود هو ملف CSRF الذي عيّنه oauth2-proxy عند الخروج، فإن المسار لا يدخل في حلقة مفرغة. بل يتوقف عند الاستدعاء الراجع (callback)، ويحدد السجل الحالة:

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.

تشترك ملفات تعريف الارتباط المفقودة في الأسباب الثلاثة الأولى أدناه؛ انحراف الساعة هو سبب آخر لفشل التحقق. تحقق من هذه الأسباب الأربعة بالترتيب.

  1. cookie_secure = true بينما وصل المتصفح إلى الموقع عبر HTTP عادي. باستثناء localhost، لن يخزن المتصفح ملف تعريف ارتباط يحمل علامة Secure على أصل http://، لذا لن يتم إرساله أبداً. قم بإنهاء TLS (أمن طبقة النقل) بشكل صحيح، أو عيّن cookie_secure = false فقط أثناء الاختبار على localhost.
  2. قيمة cookie_domains لا تغطي اسم المضيف في شريط العنوان. .example.com تغطي app.example.com ولا تفعل شيئاً على الإطلاق لـ app.example.net.
  3. المتصفح يقوم بإسقاط ملف تعريف الارتباط. قد تؤدي إضافة خصوصية صارمة أو حظر ملفات تعريف الارتباط الخاصة بطرف ثالث إلى إزالة _oauth2_proxy_csrf بين إعادة التوجيه الصادرة والاستدعاء الراجع، أو إزالة ملف تعريف ارتباط الجلسة بعد ذلك.
  4. انحراف الساعة. إذا كانت ساعة الخادم متقدمة كثيراً عن ساعة المزوّد، فقد يظهر رمز الهوية (ID token) منتهي الصلاحية ويفشل التحقق. يجب أن يبلغ timedatectl عن System clock synchronized: yes.

هناك سبب إضافي يؤدي إلى خطأ CSRF دون وجود أي إعداد خاطئ. افتراضياً، يحتفظ oauth2-proxy بملف تعريف ارتباط CSRF واحد، لذا فإن علامتي تبويب تبدآن تسجيل الدخول في نفس اللحظة ستؤديان إلى الكتابة فوق بعضهما البعض. يمنح cookie_csrf_per_request = true كل عملية تسجيل دخول ملفها الخاص.

راقب ما يحدث من جانب الخادم بدلاً من التخمين:

sudo journalctl -u oauth2-proxy -f

حمّل التطبيق في نافذة خاصة. يتم تسجيل كل طلب مع حالته، لذا فإن الاستدعاء الراجع الذي يتبعه مباشرة إعادة توجيه أخرى إلى تسجيل الدخول هو الحلقة المفرغة، ومسجل في السجلات.

المسارات التي يجب أن تتخطى تسجيل الدخول: واجهات برمجة التطبيقات (APIs)، وخطافات الويب (webhooks)، وwebsockets

يفترض المصادقة الأمامية (Forward auth) وجود متصفح يحمل ملف تعريف ارتباط (cookie). ستفشل الطلبات القادمة من جهات لا تستخدم متصفحاً.

عميل API الذي يرسل Authorization: Bearer <token> لا يملك ملف تعريف ارتباط، لذا فإن إعدادات الـ proxy المذكورة أعلاه ستوجهه إلى صفحة تسجيل الدخول الخاصة بـ 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 كان يمكن خداعها لاستثناء مسار محمي عبر طلب يستخدم مقاطع نقطية، أو شرطة مائلة مزدوجة في البداية، أو فاصلة منقوطة (تحذير GHSA-63jm-59jj-478j)، ولم يمنع تثبيت التعبيرات ذلك. الإصدار المُصحح يرفض استثناء مثل هذه المسارات الغامضة، لذا تحقق من أن مساراتك العامة لا تزال تطابق بعد الترقية.

تعد الـ websockets الحالة التي يخطئ فيها الكثيرون. طلب الترقية (upgrade request) هو طلب HTTP GET عادي يحمل نفس ملفات تعريف الارتباط مثل أي طلب آخر، لذا فهو يجتاز الفحص بشكل طبيعي ولا يحتاج إلى استثناء. ما يتعطل هو عملية الـ proxy المحيطة به. بدون ترويسات Upgrade وConnection في الموقع المحمي، لا تكتمل الترقية أبداً ويستمر عميل التطبيق في إعادة المحاولة إلى ما لا نهاية مع ظهور رسالة WebSocket connection ... failed في وحدة تحكم المتصفح. استثناء المسار لا يحل شيئاً هنا، لأن الطلب كان مصادقاً عليه بالفعل.

هناك قيد حقيقي واحد ينطبق. يتم إجراء الفحص مرة واحدة عند الترقية. الـ websocket الذي يظل مفتوحاً لساعات لا يتم فحصه مرة أخرى، لذا فإن حذف مستخدم من المزود لا يغلق المقبس (socket) الذي يحتفظ به بالفعل. أعد تشغيل التطبيق لقطع الاتصالات النشطة.

تخزين الجلسة، وملف تعريف الارتباط الذي يتجاوز حجمه المسموح

افتراضياً، تُخزَّن الجلسة بالكامل داخل ملف تعريف الارتباط (cookie)، مشفرة باستخدام 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 قبل أن يرى التطبيق الطلب.

انقل الجلسة إلى جانب الخادم (server-side) عند حدوث ذلك:

session_store_type = "redis"
redis_connection_url = "redis://127.0.0.1:6379"

يحتفظ المتصفح حينها بتذكرة قصيرة، بينما تُحفظ الجلسة المشفرة في Redis. التكلفة هنا هي الحاجة إلى خدمة يجب أن تظل تعمل: إذا توقف Redis، لا يستطيع oauth2-proxy تحميل الجلسات؛ وفقدان بيانات الجلسة المخزنة يجبر جميع المستخدمين على تسجيل الدخول مجدداً. أما تخزين الجلسة في ملف تعريف الارتباط فله تكلفته الخاصة، وهي أن طلبين يقومان بتحديث نفس الجلسة في اللحظة ذاتها قد يتصادمان ويجبران المستخدم على إعادة تسجيل الدخول.

ما لا يوفره المصادقة الأمامية (Forward Auth)

هذه بوابة عند المدخل. هي ليست تخويلاً داخل التطبيق، وهذا الفرق يحدد ما إذا كان هذا النهج يناسب حالتك.

بمجرد عبور المستخدم، يرى التطبيق ما كان يراه دائماً. إذا كان للتطبيق أدوار خاصة به، فإن المصادقة الأمامية لا تملؤها، إلا إذا كان التطبيق يدعم المصادقة المعتمدة على الترويسات (headers) ويقوم بربط ترويسة بحساب ما. تطبيق Grafana يدعم ذلك من خلال إعدادات auth.proxy. معظم التطبيقات ذاتية الاستضافة لا تدعم ذلك، لذا فإن كل من يعبر البوابة يظهر للتطبيق كهوية واحدة، وغالباً ما تكون هذه الهوية هي هوية المدير (admin).

كما أنها لا تحمي رموز API الخاصة بالتطبيق. رمز الوصول الشخصي (personal access token) الصادر عن التطبيق يوثّق الدخول إلى التطبيق نفسه، وليس إلى oauth2-proxy، لذا يتوقف الرمز عن العمل بمجرد وضع البوابة أمامه. استثنِ مسار API لإعادته للعمل، وسيصبح هذا الرمز هو الشيء الوحيد الذي يحمي المسار. أنت الآن تشغّل نظامي مصادقة على خدمة واحدة، بينما يغطي نظام SSO واحداً منهما فقط.

إلغاء الصلاحيات هو الفجوة الثالثة. حذف مستخدم من مزود الهوية يوقف عمليات تسجيل الدخول الجديدة، لكن oauth2-proxy لا يتحقق من الجلسة الحالية مع المزود حتى يحين موعد cookie_refresh. مع إيقاف التحديث (refresh)، تظل ملفات تعريف الارتباط (cookie) الخاصة بالجلسة صالحة حتى تنتهي صلاحيتها، والقيمة الافتراضية لـ cookie_expire هي 168 ساعة، وهو ما قد يعني أسبوعاً من الوصول لشخص قمت بإزالته للتو. اضبط cookie_refresh على قيمة قصيرة، مثل ساعة واحدة. عندما يرفض المزود عملية التحديث لأن رمز التحديث الخاص بالمستخدم لم يعد صالحاً، يقوم oauth2-proxy بمسح الجلسة وإجبار المستخدم على تسجيل دخول جديد عند الطلب التالي الذي يحاول التحديث. لا يتم دعم التحديث من قبل كل المزودين، لذا اختبره مع مزودك.

سجل التدقيق (audit trail) يتوقف أيضاً عند البوابة. يسجل oauth2-proxy من عبر ومتى. بينما يسجل التطبيق جلسة غير مسماة. إذا كان عليك الإجابة عن سؤال من قام بتغيير إعداد ما، فإن هوية الترويسة في التطبيق هي الحد الأدنى، والحسابات الحقيقية لكل مستخدم هي الإجابة الدقيقة.

متى يكون دفع ضريبة SSO هو الخيار الأفضل

تعد المصادقة الأمامية (Forward auth) الأداة المناسبة عندما لا يحتوي التطبيق على نظام تسجيل دخول على الإطلاق، أو عندما يستخدم كلمة مرور مشتركة، وتريد مكاناً واحداً لإضافة وإزالة المستخدمين. يستغرق إعدادها فترة بعد الظهر وعملية إضافية واحدة، وهي تعمل مع أي تطبيق يتحدث بروتوكول HTTP.

تكون هذه الأداة هي الخيار الخاطئ عندما يحتاج أشخاص مختلفون إلى صلاحيات مختلفة داخل التطبيق نفسه. لا يمكن للبوابة التعبير عن قواعد مثل "يمكن لـ Ana تعديل لوحات التحكم بينما لا يمكن لـ Bo سوى قراءتها". إذا كان المورّد يبيع فئة SSO، فإن ميزة تعيين المجموعات إلى الأدوار (group-to-role mapping) هي في العادة ما تشتريه فعلياً، وإعادة بناء ذلك باستخدام الترويسات وقواعد الـ proxy أكثر هشاشة من الدفع مقابل الحصول عليها. يجدر بك قراءة نمط التسعير خلف فئات SSO تلك قبل اتخاذ قرارك في أي من الاتجاهين.

أي تطبيق يحتوي على عميل للهاتف المحمول أو سطح المكتب لا يحمل ملفات تعريف ارتباط المتصفح (browser cookies) سيواجه صعوبة مع البوابة في كل طلب.

FAQ

ما هو المصادقة الأمامية (Forward Auth)؟

المصادقة الأمامية هي نمط يطلب فيه الـreverse proxy من خدمة مصادقة منفصلة التحقق من كل طلب وارد قبل تمريره إلى الخدمة الخلفية. يرسل الـproxy ترويسات الطلب إلى نقطة نهاية مثل /oauth2/auth ويقرأ رمز الحالة. الرمز 202 يعني السماح بالمرور، لذا يمر الطلب الأصلي إلى التطبيق. الرمز 401 يعني عدم وجود جلسة صالحة، لذا يعيد الـproxy توجيه المتصفح إلى صفحة تسجيل الدخول. يطبّق Nginx هذا النمط باستخدام التوجيه auth_request، وTraefik عبر الـmiddleware forwardAuth، وCaddy باستخدام forward_auth.

لماذا يعيد oauth2-proxy توجيهي إلى صفحة تسجيل الدخول في حلقة مفرغة؟

ملف تعريف ارتباط الجلسة (session cookie) مفقود أو فشل التحقق منه، لذا يجد كل فحص أن الجلسة غير صالحة ويعيدك إلى تسجيل الدخول. الحالات التي تستخدم أسرار ملفات تعريف ارتباط (cookie secrets) مختلفة ترفض ملفات تعريف الارتباط الخاصة ببعضها البعض. سبب آخر هو cookie_secure = true على موقع وصل إليه المتصفح عبر HTTP عادي، لأن المتصفح لن يخزن ملف تعريف ارتباط Secure على أصل http://، باستثناء localhost. تحقق أيضاً من قيمة cookie_domains التي قد لا تغطي اسم المضيف في شريط العنوان. اقرأ ترويسة 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/، وتأكد من تشغيل الإصدار v7.15.5 أو أحدث، حيث تم إصلاح ثغرة تجاوز حرجة في هذه الاستثناءات. تتطلب الاستثناءات الخاصة بطريقة معينة أن يحافظ طلب المصادقة على الطريقة الأصلية؛ أمثلة nginx وCaddy تقوم بإجراء فحوصات GET، لذا تعامل مع هذه الاستثناءات في توجيه الـreverse proxy. إذا كان عملاء الـAPI لديك يحملون بالفعل JWTs صالحة صادرة عن المزود المكوّن مع جمهور (audience) مقبول، فإن skip_jwt_bearer_tokens = true يقبل هذه الرموز بدلاً من ملف تعريف الارتباط ويحافظ على حماية المسار. يجب أن يطابق الجمهور client_id أو جمهوراً مكوّناً عبر extra_jwt_issuers. أي شيء مدرج في skip_auth_routes يكون غير مصادق عليه للجميع، لذا اجعل كل تعبير ضيقاً قدر الإمكان حسب ما يسمح به المتصل.

هل يمنح oauth2-proxy التطبيق صلاحيات لكل مستخدم؟

لا. إنه بوابة، وليس نظام تخويل. هو يقرر من يصل إلى التطبيق، وكل من يصل يبدو متطابقاً بالنسبة للتطبيق ما لم يقم ذلك التطبيق بقراءة ترويسات الهوية وربطها بالحسابات. يمكن لـGrafana القيام بذلك من خلال إعدادات auth.proxy الخاصة بها. معظم التطبيقات ذاتية الاستضافة لا تستطيع ذلك، لذا يتشارك كل شخص يتجاوز البوابة نفس الهوية الواحدة التي يعمل بها التطبيق.

هل يمكن لأحد تجاوز oauth2-proxy عن طريق تعيين ترويسة الهوية بنفسه؟

نعم، إذا كان بإمكانه الوصول إلى التطبيق مباشرة. تصل الهوية كترويسة عادية مثل X-Auth-Request-Email، ويثق التطبيق بكل ما يتلقاه. أي شخص يمكنه فتح اتصال بمنفذ التطبيق يمكنه إرسال تلك الترويسة والتحول إلى أي مستخدم. اربط التطبيق بـ127.0.0.1، أو أبقه على شبكة Docker داخلية بدون منفذ منشور، وتأكد من ذلك عبر sudo ss -tlnp.

هل كان هذا المقال مفيدًا؟

#oauth2-proxy#sso#oidc#reverse-proxy#forward-auth