nginx http shibboleth
v2.0.2
Modul ini memungkinkan Nginx untuk bekerja dengan Shibboleth, melalui otorisasi fastcgi Shibboleth. Modul ini memerlukan konfigurasi spesifik agar berfungsi dengan benar, serta aplikasi Otorisasi FastCGI Shibboleth yang tersedia di sistem. Ini bertujuan untuk mirip dengan bagian -bagian dari MOD_SHIB Apache, meskipun pengaturan otorisasi dan otentikasi Shibboleth dikonfigurasi melalui shibboleth2.xml daripada dalam konfigurasi server web.
Dengan modul ini yang dikonfigurasi terhadap blok location , permintaan yang masuk diotorisasi dalam Nginx berdasarkan hasil subrequest ke Fastcgi Otoration Shibboleth. Dalam proses ini, modul ini dapat digunakan untuk menyalin atribut pengguna dari respons otorizer yang berhasil ke dalam permintaan asli Nginx sebagai header atau parameter lingkungan untuk digunakan oleh aplikasi backend apa pun. Jika otorisasi tidak berhasil, status respons otorisator dan header dikembalikan ke klien, menolak akses atau mengarahkan kembali browser pengguna yang sesuai (seperti ke halaman wayf, jika demikian dikonfigurasi).
Modul ini bekerja pada fase akses dan karenanya dapat dikombinasikan dengan modul akses lainnya (seperti access , auth_basic ) melalui Petunjuk satisfy . Modul ini juga dapat dikompilasi bersama ngx_http_auth_request_module , meskipun penggunaan kedua modul ini di blok location yang sama tidak diuji dan tidak disarankan.
Baca lebih lanjut tentang perilaku di bawah ini dan konsultasikan konfigurasi untuk catatan penting tentang menghindari spoofing jika menggunakan header untuk atribut.
Untuk informasi lebih lanjut tentang mengapa ini adalah modul khusus, lihat https://forum.nginx.org/read.php?2.238523.238523#msg-238523
Arahan berikut ditambahkan ke dalam file konfigurasi nginx Anda. Konteks yang disebutkan di bawah ini menunjukkan di mana mereka dapat ditambahkan.
http , server , locationoffMengaktifkan modul permintaan auth shibboleth di dan set URI yang akan diminta untuk otorisasi. URI yang dikonfigurasi harus merujuk ke blok lokasi nginx yang menunjuk ke otorisasi shibboleth fastcgi Anda.
Status HTTP dan header dari respons yang dihasilkan dari sub-permintaan ke URI yang dikonfigurasi akan dikembalikan ke pengguna, sesuai dengan spesifikasi Otoritas FastCGI. Peringatan satu (yang berpotensi signifikan) adalah bahwa karena cara Nginx beroperasi saat ini sehubungan dengan subrequests (apa yang dituntut oleh penulis secara efektif), badan permintaan tidak akan diteruskan ke otorisasi, dan demikian pula, badan respons dari otorisasi tidak akan dikembalikan ke klien.
Namun, URI yang dikonfigurasi tidak terbatas menggunakan backend FastCGI untuk menghasilkan respons. Ini mungkin berguna selama pengujian atau sebaliknya, karena Anda dapat menggunakan arahan Nginx yang return dan rewrite untuk menghasilkan respons yang sesuai. Selain itu, modul ini dapat digunakan dengan otorisasi FastCGI apa pun , meskipun operasi dapat dipengaruhi oleh peringatan di atas.
Peringatan
Arahan shib_request tidak lagi membutuhkan bendera shib_authorizer . Ini harus dihapus agar nginx memulai. Tidak ada perubahan lain yang diperlukan.
http , server , locationnone Atur variable ke value yang ditentukan setelah permintaan auth telah selesai. value mungkin berisi variabel dari respons permintaan auth. Misalnya, $upstream_http_* , $upstream_status , dan variabel lain yang disebutkan dalam dokumentasi NGINX_HTTP_UPSTREAM_MODULE.
Petunjuk ini dapat digunakan untuk memperkenalkan atribut Shibboleth ke dalam lingkungan aplikasi backend, seperti $ _server untuk aplikasi php fastcgi dan merupakan metode yang disarankan untuk melakukannya. Lihat dokumentasi konfigurasi untuk contoh.
http , server , locationoffCatatan
Ditambahkan dalam v2.0.0.
Salin atribut dari respons otorisasi shibboleth ke dalam permintaan utama sebagai header, membuatnya tersedia untuk server dan aplikasi hulu. Gunakan opsi ini hanya jika hulu/aplikasi Anda tidak mendukung parameter server melalui shib_request_set .
Dengan pengaturan ini diaktifkan, header respons otorisasi yang dimulai dengan Variable-* diekstraksi, melucuti Variable- -substring dari nama header, dan disalin ke permintaan utama sebelum dikirim ke backend. Misalnya, header respons otorisator seperti Variable-Commonname: John Smith akan menghasilkan Commonname: John Smith ditambahkan ke permintaan utama, dan dengan demikian dikirim ke backend.
Waspadalah terhadap spoofing - Anda harus memastikan bahwa aplikasi backend Anda dilindungi dari injeksi header. Konsultasikan dengan contoh konfigurasi tentang cara mencapai ini.
Modul ini dapat dikompilasi secara statis atau dinamis, karena pengenalan modul dinamis di Nginx 1.9.11. Hasil utama modul dinamis adalah bahwa mereka dapat dimuat, sebagai lawan dari modul statis yang ada secara permanen dan diaktifkan.
Cara termudah untuk mendapatkan versi kemasan dari modul ini adalah dengan menggunakan alat PKG-OSS dari Nginx, yang menyediakan pengemasan modul dinamis untuk instalasi di samping rilis resmi Nginx dari repositori utama dan membantu menghindari kebutuhan untuk mengkompilasi Nginx dengan tangan.
Jika tidak, untuk mengkompilasi nginx dengan modul ini secara dinamis, berikan opsi berikut ke ./configure saat membangun Nginx:
--Add-Dynamic-Module = <path>
Anda perlu secara eksplisit memuat modul di nginx.conf Anda dengan memasukkan:
load_module /path/to/modules/ngx_http_shibboleth_module.so;
dan muat ulang atau restart nginx.
Untuk mengkompilasi nginx dengan modul ini secara statis, berikan opsi berikut ke ./configure saat membangun Nginx:
--Add-Module = <path>
Dengan build statis, tidak diperlukan pemuatan tambahan karena modul tersebut built-in ke nginx.
Untuk detail lengkap tentang mengonfigurasi lingkungan nginx/shibboleth, lihat dokumentasi di https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/config.rst.
Contoh blok server terdiri dari yang berikut:
#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;
}Perhatikan bahwa kami menggunakan header-more-nginx-module untuk membersihkan header input yang berpotensi berbahaya dan menghindari potensi spoofing. Contoh terakhir dengan variabel lingkungan tidak rentan terhadap spoofing header, selama backend membaca data dari parameter lingkungan saja .
Konfigurasi default tersedia untuk menghapus header dasar dari Shibboleth Authorizer, tetapi Anda harus memastikan Anda menulis arahan yang jelas untuk semua atribut penggunaan aplikasi Anda. Ingatlah bahwa beberapa aplikasi akan mencoba membaca atribut Shibboleth dari lingkungan dan kemudian kembali ke header, jadi tinjau kode aplikasi Anda bahkan jika Anda tidak menggunakan shib_request_use_headers .
Dengan menggunakan shib_request_set , file params default tersedia yang dapat Anda gunakan sebagai Nginx include untuk memastikan semua variabel inti shibboleth dapat ditularkan dari pengurus fastcgi ke aplikasi. Sejumlah atribut default disertakan jadi hapus yang tidak diperlukan oleh aplikasi Anda dan tambahkan atribut Federasi atau IDP yang Anda butuhkan. File params default ini dapat digunakan kembali untuk hulu yang bukan Fastcgi hanya dengan mengubah arahan fastcgi_param ke uwsgi_param , scgi_param atau sebagainya.
Subrequests, seperti permintaan Shibboleth Auth, tidak diproses melalui filter header. Ini berarti bahwa arahan bawaan seperti add_header tidak akan berfungsi jika dikonfigurasi sebagai bagian dari blok A /shibauthorizer . Jika Anda perlu memanipulasi header subrequest, gunakan more_set_headers dari headers-more .
Lihat https://forum.nginx.org/read.php?29.257271.257272#msg-257272.
Modul ini mengikuti spesifikasi Otorizer FastCGI jika memungkinkan, tetapi memiliki beberapa penyimpangan penting - dengan alasan yang bagus. Perilakunya demikian:
Subrequest otoriser terdiri dari semua aspek dari permintaan asli, kecuali badan permintaan karena Nginx tidak mendukung buffering dari badan permintaan. Karena otorisasi shibboleth fastcgi tidak mempertimbangkan badan permintaan, ini bukan masalah.
Jika SubRequest Authorizer mengembalikan status 200 , akses diizinkan.
Jika shib_request_use_headers diaktifkan, dan header respons dimulai dengan Variable-* diekstraksi, melucuti Variable- -substring dari nama header, dan disalin ke dalam permintaan utama. Header respons otorisator lainnya tidak diawali dengan Variable- dan badan respons diabaikan. SPEC FastCGI meminta pasangan Variable-* nilai nama untuk dimasukkan dalam lingkungan fastcgi, tetapi kami menjadikannya header sehingga karena dapat digunakan dengan backend (seperti proxy_pass ) dan tidak hanya membatasi diri pada aplikasi FastCGI. Dengan meneruskan data Variable-* sebagai header sebagai gantinya, kami akhirnya mengikuti perilaku ShibUseHeaders On di mod_shib for apache, yang melewati atribut pengguna ini sebagai header.
Untuk meneruskan atribut sebagai variabel lingkungan (setara dengan ShibUseEnvironment On dalam mod_shib ), atribut harus diekstraksi secara manual menggunakan arahan shib_request_set untuk setiap atribut. Ini tidak dapat (saat ini) dilakukan secara massal untuk semua atribut karena setiap backend dapat menerima parameter dengan cara yang berbeda ( fastcgi_param , uwsgi_param dll). Permintaan tarik dipersilakan untuk mengotomatiskan perilaku ini.
Jika SubRequest Otority mengembalikan status lain (termasuk pengalihan atau kesalahan), status dan header respons otorisator dikembalikan ke klien.
Ini berarti bahwa pada 401 Unauthorized atau 403 Forbidden , akses akan ditolak dan header (seperti WWW-Authenticate ) dari otorisasi akan diteruskan ke klien. Semua respons otorisator lainnya (seperti pengalihan 3xx ) diteruskan kembali ke klien, termasuk status dan header, yang memungkinkan pengalihan seperti yang ke halaman Wayf dan Shibboleth Responder ( Shibboleth.sso ) bekerja dengan benar.
Spesifikasi Otoritas FastCGI meminta badan respons untuk dikembalikan ke klien, tetapi karena Nginx saat ini tidak mendukung buffering respons subRequest ( NGX_HTTP_SUBREQUEST_IN_MEMORY ), badan respons otoriter secara efektif diabaikan. Solusi adalah agar Nginx melayani error_page sendiri, seperti itu:
location /secure {
shib_request /shibauthorizer;
error_page 403 /shibboleth-forbidden.html;
...
} Ini melayani halaman kesalahan yang diberikan jika Otoritas Shibboleth menyangkal akses pengguna ke lokasi ini. Tanpa error_page yang ditentukan, Nginx akan melayani halaman kesalahan generiknya.
Perhatikan bahwa ini tidak berlaku untuk responden Shibboleth (biasanya di -host di Shibboleth.sso ) karena merupakan responden fastcgi dan nginx sepenuhnya kompatibel dengan ini karena tidak ada subrrequest yang digunakan.
Untuk detail lebih lanjut, lihat https://forum.nginx.org/read.php?2.2384444.238453.
Sementara modul ini diarahkan khusus untuk pengurus Fastcgi Shibboleth, kemungkinan akan bekerja dengan otorisasi lain, mengingat penyimpangan dari spek di atas.
Tes secara otomatis dijalankan pada tindakan GitHub (menggunakan konfigurasi ini) setiap kali komit baru dilakukan ke repositori atau ketika permintaan tarik baru dibuka. Jika ada sesuatu yang rusak, Anda akan diberitahu dan hasilnya akan dilaporkan di GitHub.
Tes ditulis menggunakan kombinasi skrip bash sederhana untuk kompilasi modul kami dengan versi dan konfigurasi NginX yang berbeda dan perancah uji tes :: Nginx Perl untuk pengujian integrasi. Konsultasikan dengan tautan sebelumnya untuk informasi tentang cara memperluas tes, dan juga merujuk ke tes yang mendasarinya :: dokumentasi dasar tentang aspek -aspek seperti fungsi blok ().
Tes integrasi dijalankan secara otomatis oleh CI tetapi juga dapat dijalankan secara manual (membutuhkan perl & cpan untuk dipasang):
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 provePermintaan dukungan untuk konfigurasi Shibboleth dan pengaturan NGINX atau server web harus diarahkan ke milis pengguna komunitas Shibboleth. Lihat https://www.shibboleth.net/community/lists/ untuk detailnya.
Karena sifat kompleks Nginx/Fastcgi/Shibboleth Stack, masalah konfigurasi debugging bisa sulit. Inilah beberapa poin utama:
Konfirmasikan bahwa nginx-http-shibboleth berhasil dibangun dan diinstal dalam NginX. Anda dapat memeriksa dengan menjalankan nginx -V dan memeriksa output untuk --add-module=[path]/nginx-http-shibboleth atau --add-dynamic-module=[path]/nginx-http-shibboleth .
Jika menggunakan modul dinamis untuk Nginx, konfirmasi Anda telah menggunakan Petunjuk load_module untuk memuat modul ini. Penggunaan shib_request Anda dan arahan lainnya akan gagal jika Anda lupa memuat modul.
Jika menggunakan versi Nginx yang berbeda dengan yang kami uji dengan atau jika Anda menggunakan modul pihak ketiga lainnya, Anda harus menjalankan suite tes di atas untuk mengkonfirmasi kompatibilitas. Jika ada tes yang gagal, periksa konfigurasi Anda atau pertimbangkan untuk memperbarui versi Nginx Anda.
Konfigurasi Shibboleth: Periksa konfigurasi shibboleth2.xml Anda dan konfigurasi terkait untuk memastikan host, jalur, dan atribut Anda sedang dirilis dengan benar. Contoh konfigurasi dapat membantu Anda mengidentifikasi "gotchas" kunci untuk mengkonfigurasi shibboleth2.xml untuk bekerja dengan pengurus fastcgi.
Level Aplikasi: Di dalam kode Anda, selalu mulai dengan output debugging yang paling sederhana (seperti mencetak lingkungan permintaan) dan bekerja dari sana. Jika Anda ingin membuat aplikasi dasar dan berdiri sendiri, lihat konfigurasi botol pada wiki.
Debugging Modul Internal: Jika Anda telah dengan hati -hati memeriksa semua hal di atas, maka Anda juga dapat men -debug perilaku modul ini sendiri. Anda harus menyusun Nginx dengan dukungan debugging (via ./auto/configure --with-debug ... ) dan saat menjalankan Nginx, itu paling mudah jika Anda dapat berjalan di latar depan dengan debug logging diaktifkan. Tambahkan yang berikut ke nginx.conf Anda:
daemon off ;
error_log stderr debug ;dan jalankan nginx. Setelah memulai Nginx, Anda akan melihat baris yang berisi [debug] dan saat Anda mengajukan permintaan, penebangan konsol akan berlanjut. Jika ini tidak terjadi, maka periksa proses konfigurasi dan kompilasi Nginx Anda.
Ketika Anda akhirnya membuat permintaan yang mengenai (atau harus memohon) blok lokasi shib_request , Anda akan melihat baris seperti itu di output:
[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]"
... Jika Anda tidak melihat jenis baris ini yang berisi permintaan shib ..., atau jika Anda melihat beberapa baris di atas tetapi tidak di mana header/variabel sedang disalin, maka periksa kembali konfigurasi nginx Anda. Jika Anda masih belum ke mana pun, maka Anda dapat menambahkan garis debugging Anda sendiri ke dalam sumber (ikuti contoh modul ini) untuk akhirnya menentukan apa yang salah dan kapan. Jika melakukan ini, jangan lupa untuk mengkompilasi ulang nginx dan/atau nginx-http-shibboleth setiap kali Anda melakukan perubahan.
Jika Anda yakin telah menemukan bug di kode modul inti, maka silakan buat masalah.
Anda juga dapat mencari masalah yang ada karena kemungkinan orang lain telah mengalami masalah serupa sebelumnya.
Modul ini menggunakan versi semantik dan semua rilis ditandai di GitHub, yang memungkinkan unduhan paket tag individual.
Proyek ini dilisensikan dengan lisensi yang sama dengan Nginx, lisensi seperti BSD 2-Clause.
