تنزيل nginx http shibboleth - nginx http shibboleth CODE

nginx http shibboleth

بيانات الموقع

v2.0.2

تنزيل

وحدة طلب SHIBBOLETH AUTH لـ NGINX

تتيح هذه الوحدة Nginx العمل مع Shibboleth ، عن طريق مؤلف Shibboleth's fastcgi. تتطلب هذه الوحدة تكوينًا محددًا من أجل العمل بشكل صحيح ، وكذلك تطبيق SHIBBOLETH's FastCGI Authorizer متاح على النظام. يهدف إلى أن تكون مشابهة لأجزاء من MOD_SHIB من Apache ، على الرغم من تكوين إعدادات التخويل والتوثيق Shibboleth عبر shibboleth2.xml بدلاً من تكوين خادم الويب.

مع تكوين هذه الوحدة مقابل كتلة location ، يتم التصريح للطلبات الواردة داخل NGINX بناءً على نتيجة لتكوين فرعي إلى مؤلف Shibboleth's FastCGI. في هذه العملية ، يمكن استخدام هذه الوحدة لنسخ سمات المستخدم من استجابة تأليف ناجحة في الطلب الأصلي لـ NGINX كرؤوس أو معلمات بيئة للاستخدام من قبل أي تطبيق خلفي. إذا لم يكن التفويض ناجحًا ، يتم إرجاع حالة استجابة التأليف ورؤوسها إلى العميل ، مما يحرم من الوصول أو إعادة توجيه متصفح المستخدم وفقًا لذلك (مثل صفحة WayF ، إذا تم تكوينها).

تعمل هذه الوحدة في مرحلة الوصول ، وبالتالي قد يتم دمجها مع وحدات الوصول الأخرى (مثل access ، auth_basic ) عبر التوجيه satisfy . يمكن أيضًا تجميع هذه الوحدة إلى جانب ngx_http_auth_request_module ، على الرغم من أن استخدام كل من هذه الوحدات في نفس كتلة location لم يتم اختباره ولم ينصح به.

اقرأ المزيد عن السلوك أدناه واستشر التكوين للحصول على ملاحظات مهمة حول تجنب الخداع في حالة استخدام الرؤوس للسمات.

لمزيد من المعلومات حول سبب هذه الوحدة النمطية المخصصة ، راجع https://forum.nginx.org/read.php؟2،238523،238523#msg-238523

التوجيهات

تتم إضافة التوجيهات التالية في ملفات تكوين NGINX الخاصة بك. تظهر السياقات المذكورة أدناه أين يمكن إضافتها.

shib_request <Uri> | Off

السياق: http ، server ، location

الافتراضي: off

يقوم بتبديل وحدة طلب SHIBBOLETH Auth على وضبط URI الذي سيُطلب من التفويض. يجب أن يشير URI المكوّن إلى كتلة موقع Nginx التي تشير إلى مؤلف Shibboleth Fastcgi الخاص بك.

سيتم إرجاع حالة HTTP ورؤوس الاستجابة الناتجة عن التراجع الفرعي إلى URI المكوّن إلى المستخدم ، وفقًا لمواصفات تأليف FASTCGI. التحذير (الذي يحتمل أن يكون مهمًا) هو أنه نظرًا للطريقة التي تعمل بها Nginx في الوقت الحالي فيما يتعلق بالخصائص الفرعية (ما يتطلبه المؤلف بشكل فعال) ، فلن يتم إعادة توجيه هيئة الطلب إلى مؤلف المؤلف ، وبالمثل ، لن يتم إرجاع هيئة الاستجابة من المؤلف إلى العميل.

ومع ذلك ، لا يقتصر URIs المكوّن على استخدام الواجهة الخلفية FastCGI لإنشاء استجابة. قد يكون هذا مفيدًا أثناء الاختبار أو غير ذلك ، حيث يمكنك استخدام توجيهات NGINX return rewrite التوجيهات لإنتاج استجابة مناسبة. بالإضافة إلى ذلك ، يمكن استخدام هذه الوحدة مع أي مصحة fastcgi ، على الرغم من أن العملية قد تتأثر بالتحذير أعلاه.

تحذير

لم يعد التوجيه shib_request يتطلب علامة shib_authorizer . يجب إزالتها حتى تبدأ Nginx. لا توجد تغييرات أخرى مطلوبة.

shib_request_set <variable> <value>

السياق: http ، server ، location

الافتراضي: none

اضبط variable على value المحددة بعد اكتمال طلب AUTH. قد تحتوي value على متغيرات من استجابة طلب المصادقة. على سبيل المثال ، $upstream_http_* ، $upstream_status ، وأي متغيرات أخرى مذكورة في وثائق nginx_http_upstream_module.

يمكن استخدام هذا التوجيه لإدخال سمات shibboleth في بيئة تطبيق الواجهة الخلفية ، مثل $ _server لتطبيق fastcgi php وهي الطريقة الموصى بها للقيام بذلك. راجع وثائق التكوين للحصول على مثال.

shib_request_use_headers on | Off

السياق: http ، server ، location

الافتراضي: off

ملحوظة

أضاف في v2.0.0.

نسخ سمات من استجابة SHIBBOLETH Authorizer في الطلب الرئيسي كرؤوس ، مما يجعلها متاحة للخوادم والتطبيقات في المنبع. استخدم هذا الخيار فقط إذا لم يدعم تطبيق Upstream/Application معلمات الخادم عبر shib_request_set .

مع تمكين هذا الإعداد ، يتم استخلاص رؤوس الاستجابة للتأليف Variable-* ، وتجريد التباين Variable- من اسم الرأس ، ونسخها في الطلب الرئيسي قبل إرساله إلى الواجهة الخلفية. على سبيل المثال ، رأس استجابة للتراث مثل Variable-Commonname: John Smith إلى Commonname: John Smith إلى الطلب الرئيسي ، وبالتالي أرسل إلى الواجهة الخلفية.

احذر من الخداع - يجب عليك التأكد من حماية تطبيق الواجهة الخلفية من حقن الرؤوس. راجع مثال التكوين حول كيفية تحقيق ذلك.

تثبيت

يمكن تجميع هذه الوحدة بشكل ثابت أو ديناميكي ، لأن إدخال الوحدات الديناميكية في Nginx 1.9.11. تتمثل النتيجة العملية للوحدات الديناميكية في أنه يمكن تحميلها ، بدلاً من الوحدات الثابتة التي يتم تمكينها بشكل دائم.

تتمثل أسهل طريقة للحصول على نسخة معبأة من هذه الوحدة في استخدام أداة PKG-OSS من Nginx ، والتي توفر تغليف الوحدات النمطية الديناميكية للتثبيت إلى جانب الإصدارات الرسمية من Nginx من المستودعات الرئيسية وتساعد على تجنب الحاجة إلى تجميع Nginx باليد.

خلاف ذلك ، لتجميع nginx باستخدام هذه الوحدة ديناميكيًا ، تمرير الخيار التالي إلى ./configure عند إنشاء nginx:

 -mode-dynamic-module = <path>

ستحتاج إلى تحميل الوحدة النمطية بشكل صريح في nginx.conf من خلال تضمين:

 load_module/path/to/modules/ngx_http_shibboleth_module.so ؛

وإعادة تحميل أو إعادة تشغيل nginx.

لتجميع nginx مع هذه الوحدة بشكل ثابت ، تمرير الخيار التالي إلى ./configure عند بناء nginx:

 -module = <path>

مع بناء ثابت ، لا يلزم تحميل إضافي حيث أن الوحدة مدمجة في Nginx.

إعدادات

للحصول على تفاصيل كاملة حول تكوين بيئة Nginx/Shibboleth ، راجع الوثائق على https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/config.rst.

يتكون كتلة server مثال مما يلي:

 #FastCGI authorizer for Auth Request module
location = /shibauthorizer {
    internal ;
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibauthorizer.sock;
}

#FastCGI responder
location /Shibboleth.sso {
    include fastcgi_params;
    fastcgi_pass unix:/opt/shibboleth/shibresponder.sock;
}

# Using the ``shib_request_set`` directive, we can introduce attributes as
# environment variables for the backend application. In this example, we
# set ``fastcgi_param`` but this could be any type of Nginx backend that
# supports parameters (by using the appropriate *_param option)
#
# The ``shib_fastcgi_params`` is an optional set of default parameters,
# available in the ``includes/`` directory in this repository.
#
# Choose this type of configuration unless your backend application
# doesn't support server parameters or specifically requires headers.
location /secure-environment-vars {
    shib_request /shibauthorizer;
    include shib_fastcgi_params;
    shib_request_set $shib_commonname $upstream_http_variable_commonname ;
    shib_request_set $shib_email $upstream_http_variable_email ;
    fastcgi_param COMMONNAME $shib_commonname ;
    fastcgi_param EMAIL $shib_email ;
    fastcgi_pass unix:/path/to/backend.socket;
}

# A secured location. All incoming requests query the Shibboleth FastCGI authorizer.
# Watch out for performance issues and spoofing!
#
# Choose this type of configuration for ``proxy_pass`` applications
# or backends that don't support server parameters.
location /secure {
    shib_request /shibauthorizer;
    shib_request_use_headers on;

    # Attributes from Shibboleth are introduced as headers by the FastCGI
    # authorizer so we must prevent spoofing. The
    # ``shib_clear_headers`` is a set of default header directives,
    # available in the `includes/` directory in this repository.
    include shib_clear_headers;

    # Add *all* attributes that your application uses, including all
    #variations.
    more_clear_input_headers 'displayName' 'mail' 'persistent-id' ;

    # This backend application will receive Shibboleth variables as request
    # headers (from Shibboleth's FastCGI authorizer)
    proxy_pass http://localhost:8080;
}

لاحظ أننا نستخدم وحدة الرؤوس-nginx لمسح رؤوس الإدخال التي يحتمل أن تكون خطرة وتجنب احتمال حدوث خداع. المثال الأخير مع متغيرات البيئة ليس عرضة لخداع الرأس ، طالما أن الواجهة الخلفية تقرأ البيانات من معلمات البيئة فقط .

يتوفر التكوين الافتراضي لمسح الرؤوس الأساسية من جهاز SHIBBOLETH Authorizer ، ولكن يجب عليك التأكد من كتابة توجيهاتك الواضحة لجميع السمات التي تستخدمها التطبيق. ضع في اعتبارك أن بعض التطبيقات ستحاول قراءة سمة shibboleth من البيئة ثم تعود إلى الرؤوس ، لذا راجع رمز التطبيق الخاص بك حتى لو كنت لا تستخدم shib_request_use_headers .

مع استخدام shib_request_set ، يتوفر ملف params الافتراضي والذي يمكنك استخدامه include NGINX لضمان تمرير جميع متغيرات shibboleth الأساسية من مؤلف FastCGI إلى التطبيق. يتم تضمين العديد من السمات الافتراضية ، لذا قم بإزالة تلك غير المطلوبة من خلال التطبيق الخاص بك وإضافة سمات الاتحاد أو IDP التي تحتاجها. يمكن إعادة استخدام ملف params الافتراضي هذا للعلاج المنبع التي لا تكون fastcgi ببساطة عن طريق تغيير توجيهات fastcgi_param إلى uwsgi_param أو scgi_param أو نحو ذلك.

مسكات

لا تتم معالجة المساحات الفرعية ، مثل طلب Auth Shibboleth ، من خلال مرشحات الرأس. هذا يعني أن التوجيهات المدمجة مثل add_header لن تعمل إذا تم تكوينها كجزء من كتلة A /shibauthorizer . إذا كنت بحاجة إلى معالجة رؤوس المدى الفرعي ، فاستخدم more_set_headers من headers-more .
انظر https://forum.nginx.org/read.php؟29،257271،257272#msg-257272.

سلوك

تتبع هذه الوحدة مواصفات FastCgi Authorizer حيثما أمكن ، ولكن لديها بعض الانحرافات البارزة - لسبب وجيه. السلوك هكذا:

تتألف المكلف الفرعي للمؤلفين من جميع جوانب الطلب الأصلي ، باستثناء طلب الطلب لأن Nginx لا يدعم التخزين المؤقت لهيئات الطلب. نظرًا لأن جهاز SHIBBOLETH FASTCGI Authorizer لا يعتبر هيئة الطلب ، فهذه ليست مشكلة.
إذا كان المركز الفرعي للمؤلفين يعيد حالة 200 ، فسيتم إمكانية الوصول.
إذا تم تمكين shib_request_use_headers ، وتبدأ رؤوس الاستجابة Variable-* ، يتم استخلاصها ، وتجريد السلسلة Variable- من اسم الرأس ، ونسخها في الطلب الرئيسي. يتم تجاهل رؤوس استجابة مؤلف أخرى غير مسبوقة مع Variable- ويتم تجاهل هيئة الاستجابة. تستدعي مواصفات FastCGI أن يتم تضمين أزواج القيمة Variable-* في بيئة FastCGI ، لكننا نجعلها رؤوسًا بحيث يمكن استخدامها مع أي الواجهة الخلفية (مثل proxy_pass ) وليس فقط تقييد أنفسنا على تطبيقات fastcgi. من خلال تمرير البيانات Variable-* كرؤوس بدلاً من ذلك ، ينتهي بنا المطاف باتباع سلوك ShibUseHeaders On في mod_shib لـ Apache ، والذي يمرر سمات المستخدم هذه كرؤوس.
من أجل تمرير السمات كمتغيرات للبيئة (المكافئة لبيئة ShibUseEnvironment On في mod_shib ) ، يجب استخراج السمات يدويًا باستخدام توجيهات shib_request_set لكل سمة. لا يمكن (حاليًا) أن يتم بشكل جماعي لجميع السمات لأن كل الواجهة الخلفية قد يقبل المعلمات بطريقة مختلفة ( fastcgi_param ، uwsgi_param إلخ). طلبات السحب مرحب بها لأتمتة هذا السلوك.
إذا قام المكلف الفرعي بإرجاع أي حالة أخرى (بما في ذلك إعادة التوجيه أو الأخطاء) ، فسيتم إرجاع حالة ورؤوس الاستجابة الخاصة بـ Authorizer إلى العميل.
هذا يعني أنه في 401 Unauthorized أو 403 Forbidden ، سيتم رفض الوصول وسيتم نقل الرؤوس (مثل WWW-Authenticate ) من المؤلف إلى العميل. يتم نقل جميع استجابات المؤلفين الأخرى (مثل إعادة توجيه 3xx ) إلى العميل ، بما في ذلك الحالة والرؤوس ، مما يتيح إعادة الاتجاهات مثل تلك إلى صفحات WayF و Shibboleth Responder ( Shibboleth.sso ) للعمل بشكل صحيح.
تدعو مواصفات FastCGI Authorizer إلى إرجاع هيئة الاستجابة إلى العميل ، ولكن نظرًا لأن NGINX لا تدعم حاليًا استجابات التخزين المؤقت الفرعية ( NGX_HTTP_SUBREQUEST_IN_MEMORY ) ، يتم تجاهل هيئة استجابة التلوث بشكل فعال. الحل البديل هو أن يكون nginx يخدم error_page من تلقاء نفسه ، مثل ذلك:
```
 location /secure {
   shib_request /shibauthorizer;
   error_page 403 /shibboleth-forbidden.html;
   ...
}
```
يخدم هذا صفحة الخطأ المحددة إذا كان جهاز SHIBBOLETH Authorizer يحرم من وصول المستخدم إلى هذا الموقع. بدون تحديد error_page ، ستقدم NGINX صفحات الخطأ العامة.
لاحظ أن هذا لا ينطبق على مستجيب Shibboleth (الذي يتم استضافته عادة في Shibboleth.sso ) لأنه مستجيب fastcgi و nginx متوافق تمامًا مع هذا حيث لا يتم استخدام اختبارات فرعية.
لمزيد من التفاصيل ، راجع https://forum.nginx.org/read.php؟2،238444،238453.

في حين أن هذه الوحدة موجهة خصيصًا لمزرار FastCGI الخاص بـ Shibboleth ، فمن المحتمل أن تعمل مع مصورين آخرين ، مع الأخذ في الاعتبار الانحرافات عن المواصفات المذكورة أعلاه.

الاختبارات

يتم تشغيل الاختبارات تلقائيًا على إجراءات github (باستخدام هذا التكوين) كلما تم إجراء ارتباطات جديدة إلى المستودع أو عند فتح طلبات سحب جديدة. إذا كان هناك شيء ينهار ، فسوف يتم إبلاغك بالنتائج على Github.

تتم كتابة الاختبارات باستخدام مزيج من برنامج نصي BASH بسيط لتجميع الوحدة النمطية الخاصة بنا مع إصدارات مختلفة وتكوينات NGINX واختبار :: nginx perl scaffolding لاختبار التكامل. راجع الرابط السابق للحصول على معلومات حول كيفية تمديد الاختبارات ، وكذلك الرجوع إلى التوثيق الأساسي :: الوثائق الأساسية حول جوانب مثل وظيفة الكتل ().

يتم تشغيل اختبارات التكامل تلقائيًا بواسطة CI ولكن يمكن تشغيلها يدويًا (يتطلب تثبيت Perl & CPAN):

 cd nginx-http-shibboleth
cpanm --notest --local-lib= $HOME /perl5 Test::Nginx
# nginx must be present in PATH and built with debugging symbols
PERL5LIB= $HOME /perl5/lib/perl5 prove

المساعدة والدعم

يجب توجيه طلبات الدعم لتكوين Shibboleth وإعداد Nginx أو Web Server إلى قائمة إرسال مستخدمي مجتمع Shibboleth. انظر https://www.shibboleth.net/community/lists/ للحصول على التفاصيل.

تصحيح الأخطاء

نظرًا للطبيعة المعقدة لمكدس Nginx/FastCgi/Shibboleth ، قد يكون من الصعب تصحيح مشكلات تكوين التصحيح. هذه بعض النقاط الرئيسية:

تأكد من أن nginx-http-shibboleth تم إنشاؤه وتثبيته بنجاح داخل NGINX. يمكنك التحقق من خلال تشغيل nginx -V وفحص الإخراج من --add-module=[path]/nginx-http-shibboleth أو-- --add-dynamic-module=[path]/nginx-http-shibboleth .
إذا كنت تستخدم وحدات ديناميكية لـ NGINX ، فأؤكد أنك قد استخدمت توجيه load_module لتحميل هذه الوحدة. سيفشل استخدامك لـ shib_request والتوجيهات الأخرى إذا نسيت تحميل الوحدة النمطية.
إذا كنت تستخدم إصدارًا من NGINX يختلف عن تلك التي نختبرها أو إذا كنت تستخدم وحدات أخرى من الطرف الثالث ، فيجب عليك تشغيل جناح الاختبار أعلاه لتأكيد التوافق. في حالة فشل أي اختبارات ، تحقق من التكوين الخاص بك أو فكر في تحديث إصدار NGINX.
تكوين Shibboleth: تحقق من shibboleth2.xml والتكوين المرتبط به لضمان إطلاق المضيفين والمسارات والسمات بشكل صحيح. يمكن أن يساعدك تكوين مثال في تحديد مفتاح "GOTCHAS" لتكوين shibboleth2.xml للعمل مع مؤلف FastCGI.
مستوى التطبيق: ضمن الكود الخاص بك ، ابدأ دائمًا بأبسط إخراج تصحيح الأخطاء (مثل طباعة بيئة الطلب) والعمل من هناك. إذا كنت ترغب في إنشاء تطبيق أساسي مستقل ، فقم بإلقاء نظرة على تكوين الزجاجة على الويكي.
وحدة تصحيح الأخطاء الداخلية: إذا قمت بفحص جميع ما سبق بعناية ، فيمكنك أيضًا تصحيح سلوك هذه الوحدة نفسها. ستحتاج إلى تجميع NGINX مع دعم تصحيح الأخطاء (عبر ./auto/configure --with-debug ... ) وعند تشغيل NGINX ، يكون أسهل إذا كنت قادرًا على تشغيل المقدمة مع تمكين تسجيل الأخطاء. أضف ما يلي إلى nginx.conf الخاص بك:
```
 daemon off ;
error_log stderr debug ;
```
وتشغيل nginx. عند بدء تشغيل NGINX ، يجب أن ترى خطوطًا تحتوي على [Debug] وبينما تقوم بتقديم الطلبات ، سيستمر تسجيل وحدة التحكم. إذا لم يحدث هذا ، تحقق من عملية تكوين NGINX وتجميعها.
عندما تقوم في نهاية المطاف بتقديم طلب يضرب (أو يجب استدعاء) كتلة موقع shib_request ، سترى خطوطًا مثل ذلك في الإخراج:
```
[debug] 1234 #0: shib request handler
[debug] 1234 #0: shib request set variables
[debug] 1234 #0: shib request authorizer handler
[debug] 1234 #0: shib request authorizer allows access
[debug] 1234 #0: shib request authorizer copied header: "AUTH_TYPE: shibboleth"
[debug] 1234 #0: shib request authorizer copied header: "REMOTE_USER: [email protected]"
...
```
إذا كنت لا ترى هذه الأنواع من الخطوط التي تحتوي على طلب SHIB ... ، أو إذا رأيت بعض الخطوط أعلاه ولكن ليس حيث يتم نسخ الرؤوس/المتغيرات ، ثم تحقق من تكوين NGINX. إذا كنت لا تزال لا تصل إلى أي مكان ، فيمكنك إضافة خطوط تصحيح الأخطاء الخاصة بك إلى المصدر (اتبع أمثلة هذه الوحدة) لتحديد ما يحدث في النهاية ومتى. إذا قمت بذلك ، فلا تنسَ إعادة ترجمة Nginx و/أو nginx-http-shibboleth كلما قمت بإجراء تغيير.