shibboleth: Shibboleth Auth Request Modul für NGINX

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

RedHat Enterprise Linux 7, 8, 9 und 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-shibboleth

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-shibboleth

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_shibboleth_module.so;

Dieses Dokument beschreibt nginx-module-shibboleth v2.0.2 veröffentlicht am 26. Mai 2023.

Dieses Modul ermöglicht es NGINX, mit Shibboleth zu arbeiten, über Shibboleths FastCGI-Authorizer. Dieses Modul erfordert eine spezifische Konfiguration, um korrekt zu funktionieren, sowie die FastCGI-Authorizer-Anwendung von Shibboleth, die auf dem System verfügbar ist. Es zielt darauf ab, ähnlich zu Teilen von Apaches mod_shib zu sein, obwohl die Shibboleth-Authentifizierungs- und Autorisierungseinstellungen über shibboleth2.xml konfiguriert werden, anstatt in der Webserver-Konfiguration.

Mit diesem Modul, das gegen einen location-Block konfiguriert ist, werden eingehende Anfragen innerhalb von NGINX basierend auf dem Ergebnis eines Subrequests an Shibboleths FastCGI-Authorizer autorisiert. In diesem Prozess kann dieses Modul verwendet werden, um Benutzerattribute aus einer erfolgreichen Authorizer-Antwort in die ursprüngliche Anfrage von NGINX als Header oder Umgebungsparameter zu kopieren, die von jeder Backend-Anwendung verwendet werden können. Wenn die Autorisierung nicht erfolgreich ist, werden der Status und die Header der Authorizer-Antwort an den Client zurückgegeben, was den Zugriff verweigert oder den Browser des Benutzers entsprechend umleitet (zum Beispiel zu einer WAYF-Seite, wenn so konfiguriert).

Dieses Modul arbeitet in der Zugriffsphase und kann daher mit anderen Zugriffsmodulen (wie access, auth_basic) über die satisfy Direktive kombiniert werden. Dieses Modul kann auch zusammen mit ngx_http_auth_request_module kompiliert werden, obwohl die Verwendung beider Module im selben location-Block ungetestet ist und nicht empfohlen wird.

Lesen Sie mehr über das Verhalten unten und konsultieren Sie die Konfiguration für wichtige Hinweise zur Vermeidung von Spoofing, wenn Sie Header für Attribute verwenden.

Für weitere Informationen, warum dies ein dediziertes Modul ist, siehe https://forum.nginx.org/read.php?2,238523,238523#msg-238523

Direktiven

Die folgenden Direktiven werden in Ihre NGINX-Konfigurationsdateien eingefügt. Die unten genannten Kontexte zeigen, wo sie hinzugefügt werden können.

shib_request \<uri>|off | Kontext: http, server, location
Standard: off

Aktiviert das Shibboleth Auth Request Modul und legt die URI fest, die um Autorisierung gebeten wird. Die konfigurierte URI sollte auf einen NGINX Location-Block verweisen, der auf Ihren Shibboleth FastCGI-Authorizer zeigt.

Der HTTP-Status und die Header der Antwort, die aus dem Subrequest an die konfigurierte URI resultieren, werden dem Benutzer zurückgegeben, entsprechend der FastCGI Authorizer Spezifikation. Die eine (potenziell signifikante) Einschränkung ist, dass aufgrund der Art und Weise, wie NGINX derzeit in Bezug auf Subrequests funktioniert (was ein Authorizer effektiv erfordert), der Anfragekörper nicht an den Authorizer weitergeleitet wird, und ebenso wird der Antwortkörper vom Authorizer nicht an den Client zurückgegeben.

Konfigurierte URIs sind jedoch nicht darauf beschränkt, ein FastCGI-Backend zur Erzeugung einer Antwort zu verwenden. Dies kann während des Testens oder anderweitig nützlich sein, da Sie die integrierten return- und rewrite Direktiven von NGINX verwenden können, um eine geeignete Antwort zu erzeugen. Darüber hinaus kann dieses Modul mit jedem FastCGI-Authorizer verwendet werden, obwohl die Funktionalität durch die obige Einschränkung beeinträchtigt werden kann.

[!WARNING] Die shib_request-Direktive benötigt nicht mehr das shib_authorizer Flag. Dies muss entfernt werden, damit NGINX starten kann. Keine weiteren Änderungen sind erforderlich.

shib_request_set \<variable> \<value>
Kontext: http, server, location
Standard: none

Setzt die variable auf den angegebenen value, nachdem die Auth-Anfrage abgeschlossen ist. Der value kann Variablen aus der Antwort der Auth-Anfrage enthalten. Zum Beispiel $upstream_http_*, $upstream_status und andere Variablen, die in der nginx_http_upstream_module Dokumentation erwähnt werden.

Diese Direktive kann verwendet werden, um Shibboleth-Attribute in die Umgebung der Backend-Anwendung einzuführen, wie zum Beispiel $_SERVER für eine FastCGI PHP-Anwendung und ist die empfohlene Methode, dies zu tun. Siehe die Konfiguration Dokumentation für ein Beispiel.

shib_request_use_headers on|off | Kontext: http, server, location
Standard: off

[!NOTE] Hinzugefügt in v2.0.0.

Kopiert Attribute aus der Shibboleth-Authorizer-Antwort in die Hauptanfrage als Header, die für Upstream-Server und Anwendungen verfügbar sind. Verwenden Sie diese Option nur, wenn Ihr Upstream/Anwendung keine Serverparameter über shib_request_set unterstützt.

Mit dieser Einstellung werden Authorizer-Antwortheader, die mit Variable-\* beginnen, extrahiert, wobei der Substring Variable- aus dem Headernamen entfernt wird, und in die Hauptanfrage kopiert, bevor sie an das Backend gesendet wird. Zum Beispiel würde ein Authorizer-Antwortheader wie Variable-Commonname: John Smith dazu führen, dass Commonname: John Smith zur Hauptanfrage hinzugefügt wird und somit an das Backend gesendet wird.

Achten Sie auf Spoofing - Sie müssen sicherstellen, dass Ihre Backend-Anwendung vor der Injektion von Headern geschützt ist. Konsultieren Sie das Konfiguration Beispiel, wie Sie dies erreichen können.

Konfiguration

Für vollständige Details zur Konfiguration der NGINX/Shibboleth-Umgebung siehe die Dokumentation unter https://github.com/nginx-shib/nginx-http-shibboleth/blob/master/CONFIG.rst.

Ein Beispiel für einen server-Block besteht aus Folgendem:

#FastCGI-Authorizer für das Auth Request Modul
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;
}

## Mit der ``shib_request_set``-Direktive können wir Attribute als
## Umgebungsvariablen für die Backend-Anwendung einführen. In diesem Beispiel setzen wir
## ``fastcgi_param``, aber dies könnte jede Art von NGINX-Backend sein, das
## Parameter unterstützt (indem die entsprechende *_param-Option verwendet wird)
#
## Die ``shib_fastcgi_params`` ist eine optionale Menge von Standardparametern,
## die im ``includes/``-Verzeichnis in diesem Repository verfügbar sind.
#
## Wählen Sie diese Art von Konfiguration, es sei denn, Ihre Backend-Anwendung
## unterstützt keine Serverparameter oder erfordert speziell Header.
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;
}

## Ein gesicherter Standort. Alle eingehenden Anfragen fragen den Shibboleth FastCGI-Authorizer.
## Achten Sie auf Leistungsprobleme und Spoofing!
#
## Wählen Sie diese Art von Konfiguration für ``proxy_pass``-Anwendungen
## oder Backends, die keine Serverparameter unterstützen.
location /secure {
    shib_request /shibauthorizer;
    shib_request_use_headers on;

    # Attribute von Shibboleth werden als Header vom FastCGI
    # Authorizer eingeführt, daher müssen wir Spoofing verhindern. Die
    # ``shib_clear_headers`` ist eine Menge von Standardheader-Direktiven,
    # die im `includes/`-Verzeichnis in diesem Repository verfügbar sind.
    include shib_clear_headers;

    # Fügen Sie *alle* Attribute hinzu, die Ihre Anwendung verwendet, einschließlich aller
    #Variationen.
    more_clear_input_headers 'displayName' 'mail' 'persistent-id';

    # Diese Backend-Anwendung erhält Shibboleth-Variablen als Anfrage
    # Header (vom FastCGI-Authorizer von Shibboleth)
    proxy_pass http://localhost:8080;
}

Beachten Sie, dass wir das headers-more-nginx-module verwenden, um potenziell gefährliche Eingabeheader zu löschen und die Möglichkeit von Spoofing zu vermeiden. Das letzte Beispiel mit Umgebungsvariablen ist nicht anfällig für Header-Spoofing, solange das Backend Daten nur aus den Umgebungsparametern liest.

Eine Standardkonfiguration ist verfügbar, um die grundlegenden Header vom Shibboleth-Authorizer zu löschen, aber Sie müssen sicherstellen, dass Sie Ihre eigenen Löschdirektiven für alle Attribute schreiben, die Ihre Anwendung verwendet. Bedenken Sie, dass einige Anwendungen versuchen werden, ein Shibboleth-Attribut aus der Umgebung zu lesen und dann auf Header zurückzugreifen, also überprüfen Sie den Code Ihrer Anwendung, auch wenn Sie shib_request_use_headers nicht verwenden.

Mit der Verwendung von shib_request_set ist eine Standardparams Datei verfügbar, die Sie als NGINX include verwenden können, um sicherzustellen, dass alle Kern-Shibboleth-Variablen vom FastCGI-Authorizer an die Anwendung weitergegeben werden. Zahlreiche Standardattribute sind enthalten, also entfernen Sie die, die von Ihrer Anwendung nicht benötigt werden, und fügen Sie Föderations- oder IDP-Attribute hinzu, die Sie benötigen. Diese Standardparams-Datei kann für Upstreams, die kein FastCGI sind, wiederverwendet werden, indem einfach die fastcgi_param Direktiven in uwsgi_param, scgi_param oder Ähnliches geändert werden.

Probleme

Subrequests, wie die Shibboleth Auth-Anfrage, werden nicht durch Header-Filter verarbeitet. Das bedeutet, dass integrierte Direktiven wie add_header nicht funktionieren, wenn sie als Teil eines /shibauthorizer-Blocks konfiguriert sind. Wenn Sie Subrequest-Header manipulieren müssen, verwenden Sie more_set_headers aus dem Modul headers-more.

Siehe https://forum.nginx.org/read.php?29,257271,257272#msg-257272.

Verhalten

Dieses Modul folgt der FastCGI Authorizer Spezifikation wo immer möglich, hat jedoch einige bemerkenswerte Abweichungen - aus gutem Grund. Das Verhalten ist somit:

Ein Authorizer-Subrequest besteht aus allen Aspekten der ursprünglichen Anfrage, mit Ausnahme des Anfragekörpers, da NGINX keine Pufferung von Anfragekörpern unterstützt. Da der Shibboleth FastCGI-Authorizer den Anfragekörper nicht berücksichtigt, ist dies kein Problem.
Wenn ein Authorizer-Subrequest einen Status von 200 zurückgibt, wird der Zugriff gewährt.

Wenn shib_request_use_headers aktiviert ist und Antwortheader, die mit Variable-\* beginnen, extrahiert werden, wobei der Substring Variable- aus dem Headernamen entfernt wird, und in die Hauptanfrage kopiert werden. Andere Authorizer-Antwortheader, die nicht mit Variable- beginnen, und der Antwortkörper werden ignoriert. Die FastCGI-Spezifikation verlangt, dass Variable-* Name-Wert-Paare in die FastCGI-Umgebung aufgenommen werden, aber wir machen sie zu Headern, damit sie mit jedem Backend (wie proxy_pass) verwendet werden können und uns nicht nur auf FastCGI-Anwendungen beschränken. Indem wir die Variable-* Daten stattdessen als Header übergeben, folgen wir dem Verhalten von ShibUseHeaders On in mod_shib für Apache, das diese Benutzerattribute als Header übergibt.

Um Attribute als Umgebungsvariablen zu übergeben (das Äquivalent zu ShibUseEnvironment On in mod_shib), müssen Attribute manuell mit shib_request_set-Direktiven für jedes Attribut extrahiert werden. Dies kann (derzeit) nicht en masse für alle Attribute getan werden, da jedes Backend Parameter auf unterschiedliche Weise akzeptieren kann (fastcgi_param, uwsgi_param usw.). Pull-Requests sind willkommen, um dieses Verhalten zu automatisieren.

Wenn der Authorizer-Subrequest irgendeinen anderen Status (einschließlich Weiterleitungen oder Fehler) zurückgibt, werden der Status und die Header der Authorizer-Antwort an den Client zurückgegeben.

Das bedeutet, dass bei 401 Unauthorized oder 403 Forbidden der Zugriff verweigert wird und Header (wie WWW-Authenticate) vom Authorizer an den Client weitergegeben werden. Alle anderen Authorizer-Antworten (wie 3xx Weiterleitungen) werden an den Client zurückgegeben, einschließlich Status und Header, was Weiterleitungen wie zu WAYF-Seiten und dem Shibboleth-Responder (Shibboleth.sso) korrekt funktionieren lässt.

Die FastCGI Authorizer-Spezifikation verlangt, dass der Antwortkörper an den Client zurückgegeben wird, aber da NGINX derzeit keine Pufferung von Subrequest-Antworten unterstützt (NGX_HTTP_SUBREQUEST_IN_MEMORY), wird der Antwortkörper des Authorizers effektiv ignoriert. Eine Lösung besteht darin, NGINX eine eigene error_page bereitzustellen, wie folgt:

location /secure {
   shib_request /shibauthorizer;
   error_page 403 /shibboleth-forbidden.html;
   ...
}

Dies dient die angegebene Fehlerseite, wenn der Shibboleth-Authorizer dem Benutzer den Zugriff auf diesen Standort verweigert. Ohne error_page, wird NGINX seine generischen Fehlerseiten bereitstellen.

Beachten Sie, dass dies nicht für den Shibboleth-Responder (typischerweise gehostet unter Shibboleth.sso) gilt, da es sich um einen FastCGI-Responder handelt und NGINX damit vollständig kompatibel ist, da keine Subrequests verwendet werden.

Für weitere Details siehe https://forum.nginx.org/read.php?2,238444,238453.

Während dieses Modul speziell für den FastCGI-Authorizer von Shibboleth ausgelegt ist, wird es wahrscheinlich auch mit anderen Authorizern funktionieren, wobei die oben genannten Abweichungen von der Spezifikation zu berücksichtigen sind.

Tests

Tests werden automatisch auf GitHub Actions (unter Verwendung dieser Konfiguration) ausgeführt, wann immer neue Commits im Repository gemacht werden oder wenn neue Pull-Requests geöffnet werden. Wenn etwas kaputt geht, werden Sie informiert und die Ergebnisse werden auf GitHub gemeldet.

Die Tests sind mit einer Kombination aus einem einfachen Bash-Skript zum Kompilieren unseres Moduls mit verschiedenen Versionen und Konfigurationen von NGINX und dem Test::Nginx Perl-Testgerüst für Integrationstests geschrieben. Konsultieren Sie den vorherigen Link für Informationen zur Erweiterung der Tests und beziehen Sie sich auch auf die zugrunde liegende Test::Base Dokumentation zu Aspekten wie der blocks() Funktion.

Integrationstests werden automatisch von CI ausgeführt, können aber auch manuell ausgeführt werden (erfordert Perl & CPAN):

cd nginx-http-shibboleth
cpanm --notest --local-lib=$HOME/perl5 Test::Nginx
## nginx muss im PATH vorhanden sein und mit Debugging-Symbolen gebaut werden
PERL5LIB=$HOME/perl5/lib/perl5 prove

Hilfe & Unterstützung

Unterstützungsanfragen zur Shibboleth-Konfiguration und NGINX- oder Webserver-Einrichtung sollten an die Shibboleth-Community-Nutzermailingliste gerichtet werden. Siehe https://www.shibboleth.net/community/lists/ für Details.

Debugging

Aufgrund der komplexen Natur des nginx/FastCGI/Shibboleth-Stacks kann es schwierig sein, Konfigurationsprobleme zu debuggen. Hier sind einige wichtige Punkte:

Bestätigen Sie, dass nginx-http-shibboleth erfolgreich innerhalb von nginx gebaut und installiert wurde. Sie können dies überprüfen, indem Sie nginx -V ausführen und die Ausgabe auf --add-module=[path]/nginx-http-shibboleth oder --add-dynamic-module=[path]/nginx-http-shibboleth untersuchen.
Wenn Sie dynamische Module für nginx verwenden, bestätigen Sie, dass Sie die load_module-Direktive verwendet haben, um dieses Modul zu laden. Ihre Verwendung von shib_request und anderen Direktiven wird fehlschlagen, wenn Sie vergessen haben, das Modul zu laden.
Wenn Sie eine Version von nginx verwenden, die sich von denjenigen unterscheidet, mit denen wir testen oder wenn Sie andere Drittanbieter-Module verwenden, sollten Sie die oben genannte Test-Suite ausführen, um die Kompatibilität zu bestätigen. Wenn Tests fehlschlagen, überprüfen Sie Ihre Konfiguration oder ziehen Sie in Betracht, 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 helfen, wichtige "Probleme" bei der Konfiguration von shibboleth2.xml zu identifizieren, um mit dem FastCGI-Authorizer zu arbeiten.
Anwendungsebene: Beginnen Sie in Ihrem Code immer mit der einfachsten möglichen Debugging-Ausgabe (wie dem Drucken der Anfrageumgebung) und arbeiten Sie sich von dort aus hoch. Wenn Sie eine einfache, eigenständige Anwendung erstellen möchten, werfen Sie einen Blick auf die Bottle Konfiguration im Wiki.
Debugging der Modulinterne: Wenn Sie alles oben sorgfältig überprüft haben, können Sie auch das Verhalten dieses Moduls selbst debuggen. Sie müssen NGINX mit Debugging-Unterstützung kompiliert haben (über ./auto/configure --with-debug ...) und beim Ausführen von NGINX ist es am einfachsten, wenn Sie im Vordergrund mit aktivierter Debug-Protokollierung ausführen. Fügen Sie Folgendes zu Ihrer nginx.conf hinzu:
```
daemon off;
error_log stderr debug;
```
und führen Sie nginx aus. Beim Start von nginx sollten Sie Zeilen sehen, die [debug] enthalten, und während Sie Anfragen stellen, wird die Konsolenprotokollierung fortgesetzt. Wenn dies nicht passiert, überprüfen Sie Ihre nginx-Konfiguration und den Kompilierungsprozess.

Wenn Sie schließlich eine Anfrage stellen, die (oder die shib_request-Location-Block auslösen sollte), werden Sie Zeilen wie diese in der Ausgabe sehen:
```
[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 Art von Zeilen, die shib request ... enthalten, nicht sehen, oder wenn Sie einige der oben genannten Zeilen sehen, aber nicht, wo Header/Variablen kopiert werden, überprüfen Sie Ihre nginx-Konfiguration erneut. Wenn Sie immer noch nicht weiterkommen, können Sie Ihre eigenen Debugging-Zeilen in den Quellcode hinzufügen (folgen Sie den Beispielen dieses Moduls), um schließlich herauszufinden, was schiefgeht und wann. Wenn Sie dies tun, vergessen Sie nicht, nginx und/oder nginx-http-shibboleth neu zu kompilieren, wann immer Sie eine Änderung vornehmen.

Wenn Sie glauben, einen Fehler im Kernmodulcode gefunden zu haben, dann bitte erstellen Sie ein Issue.

Sie können auch nach bestehenden Issues suchen, da es wahrscheinlich ist, dass jemand anderes bereits auf ein ähnliches Problem gestoßen ist.

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentation für dieses Modul im GitHub Repository für nginx-module-shibboleth.