nginx http shibboleth
v2.0.2
Dieses Modul ermöglicht es Nginx, mit Shibboleth über Shibboleths Fastcgi -Autorisierer zu arbeiten. Dieses Modul erfordert eine spezifische Konfiguration, um korrekt zu arbeiten, sowie die auf dem System verfügbare FastCGI -Autorisierungsanwendung von Shibboleth. Ziel ist es, Teilen des apache mod_shib ähnlich zu sein, obwohl die Einstellungen der Shibboleth -Autorisierung und der Authentifizierung eher über Shibboleth2.xml als in der Webserverkonfiguration konfiguriert werden.
Mit diesem Modul, das gegen einen location konfiguriert ist, werden eingehende Anforderungen innerhalb von NGINX auf der Grundlage des Ergebniss einer Unterrequest zu Shibboleths FastCGI -Autorisierer autorisiert. In diesem Prozess kann dieses Modul verwendet werden, um Benutzerattribute aus einer erfolgreichen Autorizer -Antwort in die ursprüngliche Anforderung von NGINX als Header oder Umgebungsparameter zur Verwendung durch eine Backend -Anwendung zu kopieren. Wenn die Autorisierung nicht erfolgreich ist, werden der Autorizer -Antwortstatus und die Header an den Client zurückgegeben, wodurch der Zugriff verweigert oder den Browser des Benutzers entsprechend umleitet (z. B. auf eine Wayf -Seite, falls dies konfiguriert ist).
Dieses Modul funktioniert in der Zugriffsphase und kann daher über die satisfy mit anderen Zugriffsmodulen (z. B. access , auth_basic ) kombiniert werden. Dieses Modul kann auch neben ngx_http_auth_request_module kompiliert werden, obwohl die Verwendung dieser beiden Module im selben location nicht getestet und nicht empfohlen wird.
Lesen Sie mehr über das folgende Verhalten und wenden Sie sich an wichtige Hinweise zur Vermeidung von Spoofing, wenn Sie Header für Attribute verwenden.
Weitere Informationen darüber, warum dies ein dediziertes Modul ist
Die folgenden Anweisungen werden in Ihre Nginx -Konfigurationsdateien hinzugefügt. Die unten erwähnten Kontexte zeigen, wo sie hinzugefügt werden können.
http , server , locationoffSchaltet das Shibboleth -Auth -Anforderungsmodul ein und setzt URI fest, die zur Autorisierung verlangt werden. Die konfigurierte URI sollte sich auf einen Nginx -Standortblock verweisen, der auf Ihren Shibboleth Fastcgi Autorizer verweist.
Der HTTP-Status und die Header der Antwort, die sich aus der Teilnahme an den konfigurierten URI ergibt, werden gemäß der FastCGI-Autorisiererspezifikation an den Benutzer zurückgegeben. Die eine (potenziell signifikante) Einschränkung ist, dass die Anfrage nicht an den Autorisierer weitergeleitet wird, und in ähnlicher Weise wird die Antwortgremkung des Autorisators nicht an den Kunden zurückgegeben.
Konfigurierte URIs beschränken sich jedoch nicht darauf, ein FastCGI -Backend zu verwenden, um eine Antwort zu generieren. Dies kann während des Tests oder auf andere Weise nützlich sein, da Sie die rewrite Nginx -Bauungen als return verwenden können, um eine geeignete Antwort zu erstellen. Darüber hinaus kann dieses Modul mit jedem FastCGI -Autorisierer verwendet werden, obwohl der Betrieb durch die obige Einschränkung beeinflusst werden kann.
Warnung
Die shib_request -Anweisung erfordert nicht mehr die Flagge shib_authorizer . Dies muss entfernt werden, damit Nginx startet. Es sind keine anderen Änderungen erforderlich.
http , server , locationnone Legen Sie die variable auf den angegebenen value nach Abschluss der Auth -Anforderung fest. Der value kann Variablen aus der Antwort der Auth -Anforderung enthalten. Zum Beispiel $upstream_http_* , $upstream_status und alle anderen in der Dokumentation nginx_http_upstream_module erwähnten Variablen.
Diese Anweisung kann verwendet werden, um Shibboleth -Attribute in die Umgebung der Backend -Anwendung einzuführen, z. B. $ _server für eine FastCGI -PHP -Anwendung und die empfohlene Methode dafür. Ein Beispiel finden Sie in der Konfigurationsdokumentation.
http , server , locationoffNotiz
Hinzugefügt in v2.0.0.
Kopieren Sie Attribute aus der Reaktion des Shibboleth Authorizer in die Hauptanforderung als Header, sodass sie vorgelagerten Servern und Anwendungen zur Verfügung stehen. Verwenden Sie diese Option nur, wenn Ihre Upstream/Anwendung die Serverparameter nicht über shib_request_set unterstützt.
Mit dieser Einstellung werden Autorizer-Antwort-Header mit Variable-* extrahiert, wodurch die Variable- Substring aus dem Header-Namen entzieht und in die Hauptanforderung kopiert wird, bevor sie an das Backend gesendet wird. Beispielsweise würde ein Autorizer-Antwort-Header wie Variable-Commonname: John Smith zu Commonname: John Smith zur Hauptanfrage hinzugefügt und somit an das Backend gesendet.
Achten Sie vor dem Spoofing - Sie müssen sicherstellen, dass Ihre Backend -Anwendung vor den Kopfzeilen geschützt ist. Wenden Sie sich an das Konfigurationsbeispiel, um dies zu erreichen.
Dieses Modul kann entweder statisch oder dynamisch kompiliert werden, da dynamische Module in Nginx 1.9.11 eingeführt werden. Das praktische Ergebnis dynamischer Module ist, dass sie geladen werden können, im Gegensatz zu statischen Modulen, die dauerhaft vorhanden und aktiviert sind.
Der einfachste Weg, um eine verpackte Version dieses Moduls zu erhalten, besteht darin, das PKG-OSS-Tool von Nginx zu verwenden, das neben den offiziellen Releases von Nginx aus den Hauptrepositorys die Verpackung dynamischer Module zur Installation bereitstellt und die Notwendigkeit des Kompilierens von Nginx von Hand vermeidet.
Um Nginx mit diesem Modul dynamisch zu kompilieren, übergeben Sie die folgende Option an ./configure beim Erstellen von nginx:
--add-dynamic-Module = <path>
Sie müssen das Modul explizit in Ihr nginx.conf laden, indem Sie:
load_module /path/to/modules/ngx_http_shibboleth_module.so;
und Nginx neu laden oder neu starten.
Um NGINX mit diesem Modul statisch zu kompilieren, übergeben Sie die folgende Option an ./configure beim Erstellen von Nginx:
--Add-Module = <path>
Bei einem statischen Build ist keine zusätzliche Belastung erforderlich, da das Modul in Nginx integriert ist.
Ausführliche Informationen zum Konfigurieren der Umgebung von Nginx/Shibboleth finden Sie in der Dokumentation unter https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/config.rst.
Ein Beispiel server besteht aus folgenden:
#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;
}Beachten Sie, dass wir die Header-More-Nginx-Modul verwenden, um potenziell gefährliche Eingabebereiche zu löschen und das Potenzial für die Spoofierung zu vermeiden. Das letztere Beispiel mit Umgebungsvariablen ist nicht anfällig für Header -Spoofing, solange das Backend nur Daten aus den Umgebungsparametern liest.
Eine Standardkonfiguration steht zur Verfügung, um die grundlegenden Header vom Shibboleth Authorizer zu löschen. Sie müssen jedoch sicherstellen, dass Sie Ihre eigenen klaren Anweisungen für alle Attribute Ihrer Anwendung schreiben. Denken Sie daran, dass einige Anwendungen versuchen, ein Shibboleth -Attribut aus der Umgebung zu lesen und dann auf die Header zurückzufallen. Überprüfen Sie also den Code Ihrer Anwendung, auch wenn Sie nicht shib_request_use_headers verwenden.
Bei Verwendung von shib_request_set ist eine Standardparams -Datei verfügbar, die Sie als nginx include können, um sicherzustellen, dass alle Kern -Shibboleth -Variablen vom FASTCGI -Autorizer an die Anwendung übergeben werden. Zahlreiche Standardattribute sind enthalten. Entfernen Sie daher diejenigen, die nicht von Ihrer Anwendung benötigt werden, und fügen Sie die benötigten Föderations- oder IDP -Attribute hinzu. Diese Standard-Params-Datei kann für Upstreams wiederverwendet werden, die nicht durch FastCGI sind, indem einfach die Richtlinien fastcgi_param in uwsgi_param , scgi_param oder so geändert werden.
Unterrequests wie die Shibboleth -Auth -Anfrage werden nicht über Headerfilter verarbeitet. Dies bedeutet, dass integrierte Direktiven wie add_header nicht funktionieren, wenn sie als Teil des A /shibauthorizer Blocks konfiguriert werden. Wenn Sie Subrequest-Header manipulieren müssen, verwenden Sie more_set_headers aus den Modulheader headers-more .
Siehe https://forum.nginx.org/read.php?29,257271,257272#msg-257272.
Dieses Modul folgt der FastCGI -Autorisiererspezifikation, wo dies möglich ist, jedoch einige bemerkenswerte Abweichungen - aus gutem Grund. Das Verhalten ist also:
Ein Autorizer -Unterrequest besteht aus allen Aspekten der ursprünglichen Anfrage, mit Ausnahme des Anforderungsorganisation, da Nginx die Pufferung von Anforderungskörpern nicht unterstützt. Da der Shibboleth Fastcgi Autorizer die Antragsbehörde nicht berücksichtigt, ist dies kein Problem.
Wenn ein Autorizer -Unterausdruck einen 200 -Status zurückgibt, ist der Zugriff zulässig.
Wenn shib_request_use_headers aktiviert ist und Antwortheader mit Variable-* extrahiert werden, werden die Variable- Substring aus dem Header-Namen entzogen und in die Hauptanforderung kopiert. Andere Autorizer-Antwort-Header, die nicht mit Variable- vorangestellt sind, und die Antwortkörper werden ignoriert. Die FastCGI-Spezifikation fordert die Variable-* Namenswertepaare in der FastCGI-Umgebung auf, aber wir machen sie Header, so wie sie mit jedem Backend (z. B. proxy_pass ) verwendet werden können und uns nicht nur auf FastCGI-Anwendungen beschränken. Durch das Übergeben der Variable-* -Daten als Header folgen wir am Ende dem Verhalten von ShibUseHeaders On in mod_shib für Apache, das diese Benutzerattribute als Header übergibt.
Um Attribute als Umgebungsvariablen (das Äquivalent zu ShibUseEnvironment On in mod_shib ) zu übergeben, müssen Attribute für jedes Attribut manuell mit shib_request_set -Anweisungen extrahiert werden. Dies kann nicht (derzeit) für alle Attribute massenhaft gemacht werden, da jedes Backend Parameter auf andere Weise akzeptieren kann ( fastcgi_param , uwsgi_param usw.). Pull -Anfragen sind herzlich eingeladen, dieses Verhalten zu automatisieren.
Wenn der Autorizer -Unterrequest einen anderen Status zurückgibt (einschließlich Weiterleitungen oder Fehler), werden der Status und die Header der Autorizer -Antwort an den Kunden zurückgegeben.
Dies bedeutet, dass bei 401 Unauthorized oder 403 Forbidden Zugang abgelehnt wird und Header (wie WWW-Authenticate ) vom Autorisierer an den Kunden weitergegeben werden. Alle anderen Autorisiererantworten (z. B. 3xx -Weiterleitungen) werden an den Kunden weitergegeben, einschließlich Status und Header, sodass Umleitung wie solche auf Wayf -Seiten und den Responder ( Shibboleth.sso ) korrekt arbeiten kann.
Die FastCGI Autorizer -Spezifikation fordert, dass die Antwortbehörde an den Client zurückgegeben wird. Da Nginx jedoch derzeit keine Puffer -Subrequest -Antworten ( NGX_HTTP_SUBREQUEST_IN_MEMORY ) unterstützt, wird der Autorizer -Reaktionsgremium effektiv ignoriert. Eine Problemumgehung besteht darin, dass Nginx eine eigene error_page liefern, wie dies:
location /secure {
shib_request /shibauthorizer;
error_page 403 /shibboleth-forbidden.html;
...
} Dies dient der angegebenen Fehlerseite, wenn der Shibboleth Autorizer den Benutzerzugriff auf diesen Ort verweigert. Ohne angegebene error_page dient Nginx seine generischen Fehlerseiten.
Beachten Sie, dass dies nicht für den Shibboleth -Responder (typischerweise in Shibboleth.sso gehostet wird) gilt, da es sich um einen Fastcgi -Responder handelt und Nginx damit vollständig kompatibel ist, da keine Unterrequest verwendet werden.
Weitere Informationen finden Sie unter https://forum.nginx.org/read.php?2,238444,238453.
Während dieses Modul speziell auf Shibboleths FastCGI -Autorisierer ausgerichtet ist, wird es wahrscheinlich mit anderen Autorisierern zusammenarbeiten, unter Berücksichtigung der Abweichungen der oben genannten Spezifikation.
Tests werden automatisch auf GitHub -Aktionen (unter Verwendung dieser Konfiguration) ausgeführt, wenn neue Commits zum Repository durchgeführt werden oder wenn neue Pull -Anfragen geöffnet werden. Wenn etwas bricht, werden Sie informiert und die Ergebnisse werden auf GitHub gemeldet.
Tests werden unter Verwendung einer Kombination aus einem einfachen Bash -Skript zur Kompilierung unseres Moduls mit verschiedenen Versionen und Konfigurationen von Nginx und dem Test :: Nginx Perl -Test -Gerüst für Integrationstests geschrieben. Informationen zur Erweiterung der Tests finden Sie im vorherigen Link, um Informationen zur Erweiterung der Tests zu erhalten. Weitere Informationen finden Sie in den zugrunde liegenden Test :: Basisdokumentation über Aspekte wie die Blocks () -Funktion.
Integrationstests werden automatisch von CI durchgeführt, können jedoch auch manuell ausgeführt werden (muss Perl & CPAN installiert werden):
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 proveSupportanfragen für die Shibboleth -Konfiguration und Nginx- oder Webserver -Setup sollten an die Versandliste der Shibboleth -Community -Benutzer gerichtet werden. Weitere Informationen finden Sie unter https://www.shibboleth.net/community/lists/.
Aufgrund der Komplexität des Nginx/FastCGI/Shibboleth -Stacks kann die Debugging -Konfigurationsprobleme schwierig sein. Hier sind einige wichtige Punkte:
Bestätigen Sie, dass nginx-http-shibboleth in Nginx erfolgreich erstellt und installiert ist. Sie können überprüfen, indem Sie nginx -V ausführen und die Ausgabe für --add-module=[path]/nginx-http-shibboleth oder --add-dynamic-module=[path]/nginx-http-shibboleth inspizieren.
Wenn Sie dynamische Module für nginx verwenden, bestätigen Sie, dass Sie die Anweisung load_module verwendet haben, um dieses Modul zu laden. Ihre Verwendung von shib_request und anderen Anweisungen schlägt fehl, wenn Sie vergessen haben, das Modul zu laden.
Wenn Sie eine Version von Nginx verwenden, die sich von denen unterscheidet, mit denen wir getestet werden, oder wenn Sie andere Module von Drittanbietern verwenden, sollten Sie die obige Testsuite ausführen, um die Kompatibilität zu bestätigen. Wenn Tests fehlschlagen, überprüfen Sie Ihre Konfiguration oder erwägen Sie, Ihre Nginx -Version zu aktualisieren.
Shibboleth -Konfiguration: Überprüfen Sie Ihre shibboleth2.xml und die zugehörige Konfiguration, um sicherzustellen, dass Ihre Hosts, Pfade und Attribute korrekt freigegeben werden. Eine Beispielkonfiguration kann Ihnen dabei helfen, die Schlüssel "Gotchas" für die Konfiguration shibboleth2.xml so zu identifizieren, dass sie mit dem FastCGI -Autorizer arbeiten.
Anwendungsebene: Beginnen Sie in Ihrem Code immer mit der einfachsten Debugging-Ausgabe (z. B. der Drucken der Anforderungsumgebung) und arbeiten Sie von dort aus. Wenn Sie eine einfache, eigenständige App erstellen möchten, sehen Sie sich die Flaschenkonfiguration auf dem Wiki an.
Debugging Modul Interna: Wenn Sie alle oben genannten sorgfältig überprüft haben, können Sie auch das Verhalten dieses Moduls selbst debuggen. Sie müssen Nginx mit Debugging-Unterstützung (via ./auto/configure --with-debug ... ) zusammengestellt haben, und wenn Sie Nginx ausführen, ist es am einfachsten, wenn Sie mit aktiviertem Debug-Protokollieren im Vordergrund laufen können. Fügen Sie Ihrem nginx.conf Folgendes hinzu:
daemon off ;
error_log stderr debug ;und nginx ausführen. Beim Starten von NGINX sollten Sie Zeilen mit [Debug] sehen, und während Sie Anfragen stellen, wird die Konsolenprotokollierung fortgesetzt. Wenn dies nicht der Fall ist, überprüfen Sie Ihre NGINX -Konfiguration und Ihren Kompilierungsprozess.
Wenn Sie irgendwann eine Anfrage stellen, die den shib_request -Standortblock trifft (oder aufrufen sollte), sehen Sie wie in der Ausgabe Linien wie in der Ausgabe:
[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]"
... Wenn Sie diese Arten von Zeilen, die eine Shib-Anfrage enthalten, nicht sehen oder einige der obigen Zeilen sehen, jedoch nicht, wo Header/Variablen kopiert werden, überprüfen Sie Ihre Nginx-Konfiguration. Wenn Sie immer noch nirgendwo hinkommen, können Sie Ihre eigenen Debugging -Zeilen in die Quelle hinzufügen (folgen Sie den Beispielen dieses Moduls), um schließlich zu bestimmen, was und wann schief geht. Wenn Sie dies tun, vergessen Sie nicht, Nginx und/oder nginx-http-shibboleth neu zu kompilieren, wenn Sie eine Änderung vornehmen.
Wenn Sie der Ansicht sind, dass Sie einen Fehler im Core -Modulcode gefunden haben, erstellen Sie bitte ein Problem.
Sie können auch vorhandene Probleme durchsuchen, da wahrscheinlich jemand anderes auf ein ähnliches Problem gestoßen ist.
Dieses Modul verwendet semantische Versioning und alle Veröffentlichungen werden auf GitHub markiert, wodurch Paket -Downloads einzelner Tags ermöglicht werden.
Dieses Projekt ist unter derselben Lizenz lizenziert wie Nginx, die 2-Klausel-BSD-ähnliche Lizenz.
