spnego-http-auth: module NGINX pour l'authentification HTTP SPNEGO

Nécessite le plan Pro (ou supérieur) de l'abonnement GetPageSpeed NGINX Extras.

Installation

Vous pouvez installer ce module dans toute distribution basée sur RHEL, y compris, mais sans s'y limiter :

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et 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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_auth_spnego_module.so;

Ce document décrit nginx-module-spnego-http-auth v1.2.0 publié le 14 février 2026.

Ce module ajoute le support SPNEGO à nginx(http://nginx.org). Il prend actuellement en charge uniquement l'authentification Kerberos via GSSAPI

Prérequis

L'authentification a été testée avec (au moins) les éléments suivants :

Nginx 1.2 à 1.15
Internet Explorer 8 et supérieur
Firefox 10 et supérieur
Chrome 20 et supérieur
Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl)

La bibliothèque kerberos sous-jacente utilisée pour ces tests était MIT KRB5 v1.12.

Référence de configuration

Vous pouvez configurer l'authentification GSS par emplacement et/ou de manière globale :

Ces options sont requises. * auth_gss: on/off, pour faciliter la désactivation tout en laissant d'autres options dans le fichier de configuration * auth_gss_keytab: chemin absolu vers le fichier keytab contenant les informations d'identification du service

Ces options ne doivent ÊTRE spécifiées que si vous avez un keytab contenant des principaux privilégiés. Dans presque tous les cas, vous ne devez pas les mettre dans le fichier de configuration, car gss_accept_sec_context fera ce qu'il faut. * auth_gss_realm: nom du royaume Kerberos. Si cela est spécifié, le royaume n'est passé à la variable nginx $remote_user que s'il diffère de ce défaut. Pour remplacer ce comportement, définissez auth_gss_format_full sur on dans votre configuration. * auth_gss_service_name: nom principal du service à utiliser lors de l'acquisition des informations d'identification.

Si vous souhaitez autoriser uniquement un ensemble spécifique de principaux, vous pouvez utiliser la directive auth_gss_authorized_principal. La syntaxe de configuration prend en charge plusieurs entrées, une par ligne.

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

Les principaux peuvent également être autorisés à l'aide d'un motif regex via la directive auth_gss_authorized_principal_regex. Cette directive peut être utilisée avec la directive auth_gss_authorized_principal.

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

L'en-tête utilisateur distant dans nginx ne peut être défini qu'en effectuant une authentification basique. Ainsi, ce module définit un en-tête d'authentification basique fictif qui atteindra votre application backend afin de définir cet en-tête/variable nginx. Le moyen le plus simple de désactiver ce comportement est d'ajouter la configuration suivante à votre configuration de localisation.

proxy_set_header Authorization "";

Une future version du module pourrait rendre ce comportement optionnel, mais cela devrait être un contournement suffisant pour l'instant.

Si vous souhaitez activer les règles de nom local GSS pour réécrire les noms d'utilisateur, vous pouvez spécifier l'option auth_gss_map_to_local.

Délégation d'informations d'identification

Les informations d'identification utilisateur peuvent être déléguées à nginx en utilisant la directive auth_gss_delegate_credentials. Cette directive activera la délégation sans contrainte si l'utilisateur choisit de déléguer ses informations d'identification. La délégation contrainte (S4U2proxy) peut également être activée en utilisant la directive auth_gss_constrained_delegation avec la directive auth_gss_delegate_credentials. Pour spécifier le nom du fichier ccache pour stocker le ticket de service utilisé pour la délégation contrainte, définissez la directive auth_gss_service_ccache. Sinon, le nom de ccache par défaut sera utilisé.

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

Les informations d'identification déléguées seront stockées dans le répertoire tmp du système. Une fois la demande terminée, le fichier d'informations d'identification sera détruit. Le nom du fichier d'informations d'identification sera spécifié dans la variable nginx $krb5_cc_name. L'utilisation de la variable peut inclure son passage à un programme fcgi à l'aide de la directive fastcgi_param.

fastcgi_param KRB5CCNAME $krb5_cc_name;

La délégation contrainte est actuellement uniquement prise en charge en utilisant le schéma d'authentification negotiate et n'a été testée qu'avec MIT Kerberos (Utilisez à vos risques et périls si vous utilisez Heimdal Kerberos).

Repli sur l'authentification basique

Le module revient à l'authentification basique par défaut si aucune négociation n'est tentée par le client. Si vous utilisez SPNEGO sans SSL, il est recommandé de désactiver le repli sur l'authentification basique, car le mot de passe serait envoyé en texte clair. Cela se fait en définissant auth_gss_allow_basic_fallback dans le fichier de configuration.

auth_gss_allow_basic_fallback off

Ces options affectent le fonctionnement de l'authentification basique : * auth_gss_realm: nom du royaume Kerberos. Si cela est spécifié, le royaume est seulement passé à la variable nginx $remote_user s'il diffère de ce défaut. Pour remplacer ce comportement, définissez auth_gss_format_full sur 1 dans votre configuration. * auth_gss_force_realm: Authentifiez de force en utilisant le royaume configuré dans auth_gss_realm ou le royaume par défaut du système si auth_gss_realm n'est pas défini. Cela réécrira $remote_user si le client a fourni un royaume différent. Si auth_gss_format_full n'est pas défini, $remote_user n'inclura pas de royaume même si un a été spécifié par le client.

Dépannage

Vérifiez les journaux. Si vous voyez une mention de NTLM, votre client tente de se connecter en utilisant NTLMSSP, qui n'est pas pris en charge et est peu sûr.

Vérifiez que vous avez un principal HTTP dans votre keytab

Utilitaires MIT Kerberos

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

ou

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

Utilitaires Heimdal Kerberos

$ ktutil -k <path to your keytab> list

Obtenez un principal HTTP

Si vous constatez que vous n'avez pas le principal de service HTTP, que vous fonctionnez dans un environnement Active Directory, et que vous êtes lié au domaine de sorte que les outils Samba fonctionnent correctement

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

Si vous fonctionnez dans un environnement kerberos différent, vous pouvez probablement exécuter

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

Augmenter la taille maximale autorisée de l'en-tête

Dans un environnement Active Directory, le token SPNEGO dans l'en-tête Authorization inclut des informations PAC (Privilege Access Certificate), qui incluent tous les groupes de sécurité auxquels l'utilisateur appartient. Cela peut provoquer une augmentation de la taille de l'en-tête au-delà de la limite par défaut de 8kB et provoquer le message d'erreur suivant :

400 Bad Request
Request Header Or Cookie Too Large

Pour des raisons de performance, la meilleure solution est de réduire le nombre de groupes auxquels l'utilisateur appartient. Lorsque cela n'est pas pratique, vous pouvez également choisir d'augmenter la taille d'en-tête autorisée en définissant explicitement le nombre et la taille des tampons d'en-tête Nginx :

large_client_header_buffers 8 32k;

Débogage

Le module imprime toutes sortes d'informations de débogage si nginx est compilé avec l'option --with-debug, et la directive error_log a un niveau debug.

NTLM

Notez que le module ne prend pas en charge NTLMSSP dans Negotiate. NTLM, tant v1 que v2, est un protocole exploitable et doit être évité dans la mesure du possible.

Windows

Pour les environnements KDC/AD Windows, consultez la documentation ici.

Aide

Si vous ne parvenez pas à résoudre les problèmes, n'hésitez pas à ouvrir un problème sur Github et je ferai de mon mieux pour vous aider.