spnego-http-auth: NGINX-Modul für HTTP SPNEGO-Authentifizierung

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras-Abonnements.

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-spnego-http-auth

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-spnego-http-auth

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

load_module modules/ngx_http_auth_spnego_module.so;

Dieses Dokument beschreibt nginx-module-spnego-http-auth v1.2.0, veröffentlicht am 14. Februar 2026.

Dieses Modul implementiert die Unterstützung für SPNEGO in nginx (http://nginx.org). Es unterstützt derzeit nur die Kerberos-Authentifizierung über GSSAPI.

Voraussetzungen

Die Authentifizierung wurde mit (mindestens) den folgenden getestet:

Nginx 1.2 bis 1.15
Internet Explorer 8 und höher
Firefox 10 und höher
Chrome 20 und höher
Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl)

Die zugrunde liegende Kerberos-Bibliothek, die für diese Tests verwendet wurde, war MIT KRB5 v1.12.

Konfigurationsreferenz

Sie können die GSS-Authentifizierung pro Standort und/oder global konfigurieren:

Diese Optionen sind erforderlich. * auth_gss: ein/aus, um das Unsichern zu erleichtern, während andere Optionen in der Konfigurationsdatei verbleiben. * auth_gss_keytab: absoluter Pfad zum Keytab-Datei, die Dienstanmeldeinformationen enthält.

Diese Optionen sollten NUR angegeben werden, wenn Sie einen Keytab mit privilegierten Principals haben. In fast allen Fällen sollten Sie diese nicht in die Konfigurationsdatei einfügen, da gss_accept_sec_context das Richtige tun wird. * auth_gss_realm: Kerberos-Realm-Name. Wenn dies angegeben ist, wird der Realm nur an die nginx-Variable $remote_user übergeben, wenn er sich von diesem Standard unterscheidet. Um dieses Verhalten zu überschreiben, setzen Sie auth_gss_format_full auf on in Ihrer Konfiguration. * auth_gss_service_name: Dienstprinzipalname, der beim Erwerb von Anmeldeinformationen verwendet wird.

Wenn Sie nur eine bestimmte Gruppe von Principals autorisieren möchten, können Sie die Direktive auth_gss_authorized_principal verwenden. Die Konfigurationssyntax unterstützt mehrere Einträge, einen pro Zeile.

auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal <primary2>@<realm>

Principals können auch mithilfe eines Regex-Musters über die Direktive auth_gss_authorized_principal_regex autorisiert werden. Diese Direktive kann zusammen mit der Direktive auth_gss_authorized_principal verwendet werden.

auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal_regex ^(<primary2>)/(<instance>)@<realm>$

Der Remote-User-Header in nginx kann nur durch grundlegende Authentifizierung gesetzt werden. Daher setzt dieses Modul einen falschen Basic-Auth-Header, der Ihre Backend-Anwendung erreicht, um diesen Header/nginx-Variable zu setzen. Der einfachste Weg, dieses Verhalten zu deaktivieren, besteht darin, die folgende Konfiguration zu Ihrer Standortkonfiguration hinzuzufügen.

proxy_set_header Authorization "";

Eine zukünftige Version des Moduls könnte dieses Verhalten als Option anbieten, aber dies sollte vorerst eine ausreichende Umgehungslösung sein.

Wenn Sie GSS-Lokalisierungsregeln aktivieren möchten, um Benutzernamen umzuschreiben, können Sie die Option auth_gss_map_to_local angeben.

Anmeldelegation

Benutzeranmeldeinformationen können an nginx delegiert werden, indem die Direktive auth_gss_delegate_credentials verwendet wird. Diese Direktive aktiviert die uneingeschränkte Delegation, wenn der Benutzer sich entscheidet, seine Anmeldeinformationen zu delegieren. Die eingeschränkte Delegation (S4U2proxy) kann ebenfalls aktiviert werden, indem die Direktive auth_gss_constrained_delegation zusammen mit der Direktive auth_gss_delegate_credentials verwendet wird. Um den Namen der ccache-Datei anzugeben, in der das für die eingeschränkte Delegation verwendete Dienstticket gespeichert wird, setzen Sie die Direktive auth_gss_service_ccache. Andernfalls wird der Standard-ccache-Name verwendet.

auth_gss_service_ccache /tmp/krb5cc_0;
auth_gss_delegate_credentials on;
auth_gss_constrained_delegation on;

Die delegierten Anmeldeinformationen werden im temporären Verzeichnis des Systems gespeichert. Sobald die Anfrage abgeschlossen ist, wird die Anmeldeinformationsdatei gelöscht. Der Name der Anmeldeinformationsdatei wird innerhalb der nginx-Variable $krb5_cc_name angegeben. Die Verwendung der Variablen kann das Übergeben an ein FCGI-Programm über die Direktive fastcgi_param umfassen.

fastcgi_param KRB5CCNAME $krb5_cc_name;

Eingeschränkte Delegation wird derzeit nur mit dem Verhandlungsauthentifizierungsverfahren unterstützt und wurde nur mit MIT Kerberos getestet (Verwendung auf eigenes Risiko, wenn Sie Heimdal Kerberos verwenden).

Fallback auf grundlegende Authentifizierung

Das Modul fällt standardmäßig auf die grundlegende Authentifizierung zurück, wenn vom Client keine Verhandlung versucht wird. Wenn Sie SPNEGO ohne SSL verwenden, wird empfohlen, den Fallback auf die grundlegende Authentifizierung zu deaktivieren, da das Passwort im Klartext gesendet wird. Dies geschieht, indem auth_gss_allow_basic_fallback in der Konfigurationsdatei gesetzt wird.

auth_gss_allow_basic_fallback off

Diese Optionen beeinflussen den Betrieb der grundlegenden Authentifizierung: * auth_gss_realm: Kerberos-Realm-Name. Wenn dies angegeben ist, wird der Realm nur an die nginx-Variable $remote_user übergeben, wenn er sich von diesem Standard unterscheidet. Um dieses Verhalten zu überschreiben, setzen Sie auth_gss_format_full auf 1 in Ihrer Konfiguration. * auth_gss_force_realm: Erzwingt die Authentifizierung mit dem im auth_gss_realm konfigurierten Realm oder dem Systemstandard-Realm, wenn auth_gss_realm nicht gesetzt ist. Dies wird $remote_user umschreiben, wenn der Client einen anderen Realm angegeben hat. Wenn auth_gss_format_full nicht gesetzt ist, wird $remote_user keinen Realm enthalten, selbst wenn einer vom Client angegeben wurde.

Fehlersuche

Überprüfen Sie die Protokolle. Wenn Sie einen Hinweis auf NTLM sehen, versucht Ihr Client, sich über NTLMSSP zu verbinden, was nicht unterstützt und unsicher ist.

Überprüfen Sie, ob Sie einen HTTP-Prinzipal in Ihrem Keytab haben

MIT Kerberos-Dienstprogramme

$ KRB5_KTNAME=FILE:<path to your keytab> klist -k

oder

$ ktutil
ktutil: read_kt <path to your keytab>
ktutil: list

Heimdal Kerberos-Dienstprogramme

$ ktutil -k <path to your keytab> list

HTTP-Prinzipal erhalten

Wenn Sie feststellen, dass Sie den HTTP-Dienstprinzipal nicht haben, in einer Active Directory-Umgebung arbeiten, und an die Domäne gebunden sind, sodass Samba-Tools ordnungsgemäß funktionieren

$ env KRB5_KTNAME=FILE:<path to your keytab> net ads -P keytab add HTTP

Wenn Sie in einer anderen Kerberos-Umgebung arbeiten, können Sie wahrscheinlich

$ env KRB5_KTNAME=FILE:<path to your keytab> krb5_keytab HTTP

Maximale erlaubte Headergröße erhöhen

In einer Active Directory-Umgebung enthält das SPNEGO-Token im Authorization-Header PAC (Privilege Access Certificate)-Informationen, die alle Sicherheitsgruppen umfassen, zu denen der Benutzer gehört. Dies kann dazu führen, dass der Header über das Standardlimit von 8 kB hinauswächst und folgende Fehlermeldung verursacht:

400 Bad Request
Request Header Or Cookie Too Large

Aus Leistungsgründen ist die beste Lösung, die Anzahl der Gruppen, zu denen der Benutzer gehört, zu reduzieren. Wenn dies unpraktisch ist, können Sie auch die erlaubte Headergröße erhöhen, indem Sie die Anzahl und Größe der Nginx-Headerpuffer explizit festlegen:

large_client_header_buffers 8 32k;

Debugging

Das Modul gibt alle Arten von Debugging-Informationen aus, wenn nginx mit der Option --with-debug kompiliert wurde und die Direktive error_log ein debug-Level hat.

NTLM

Beachten Sie, dass das Modul NTLMSSP in Negotiate nicht unterstützt. NTLM, sowohl v1 als auch v2, ist ein ausnutzbares Protokoll und sollte nach Möglichkeit vermieden werden.

Windows

Für Windows KDC/AD-Umgebungen siehe die Dokumentation hier.

Hilfe

Wenn Sie nicht weiterkommen, zögern Sie bitte nicht, ein Problem auf Github zu eröffnen, und ich werde mein Bestes tun, um Ihnen zu helfen.