Saltar a contenido

spnego-http-auth: módulo NGINX para autenticación HTTP SPNEGO

Requiere el plan Pro (o superior) de la suscripción GetPageSpeed NGINX Extras.

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_spnego_module.so;

Este documento describe nginx-module-spnego-http-auth v1.2.0 lanzado el 14 de febrero de 2026.

Este módulo implementa soporte para SPNEGO en nginx(http://nginx.org). Actualmente solo soporta autenticación Kerberos a través de GSSAPI

Requisitos previos

La autenticación ha sido probada con (al menos) los siguientes:

  • Nginx 1.2 a 1.15
  • Internet Explorer 8 y superior
  • Firefox 10 y superior
  • Chrome 20 y superior
  • Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl)

La biblioteca kerberos subyacente utilizada para estas pruebas fue MIT KRB5 v1.12.

Referencia de configuración

Puedes configurar la autenticación GSS por ubicación y/o de manera global:

Estas opciones son requeridas. * auth_gss: on/off, para facilitar la desactivación mientras se dejan otras opciones en el archivo de configuración * auth_gss_keytab: ruta absoluta al archivo keytab que contiene las credenciales del servicio

Estas opciones SOLO deben especificarse si tienes un keytab que contiene principales privilegiados. En casi todos los casos, no deberías poner estas en el archivo de configuración, ya que gss_accept_sec_context hará lo correcto. * auth_gss_realm: nombre del reino Kerberos. Si esto se especifica, el reino solo se pasa a la variable nginx $remote_user si difiere de este valor por defecto. Para anular este comportamiento, establece auth_gss_format_full en on en tu configuración. * auth_gss_service_name: nombre del principal del servicio a utilizar al adquirir credenciales.

Si deseas autorizar solo un conjunto específico de principales, puedes usar la directiva auth_gss_authorized_principal. La sintaxis de configuración soporta múltiples entradas, una por línea.

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

Los principales también pueden ser autorizados utilizando un patrón regex a través de la directiva auth_gss_authorized_principal_regex. Esta directiva puede usarse junto con la directiva auth_gss_authorized_principal.

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

El encabezado de usuario remoto en nginx solo puede ser establecido mediante autenticación básica. Por lo tanto, este módulo establece un encabezado de autenticación básica falso que llegará a tu aplicación backend para establecer este encabezado/variable nginx. La forma más fácil de desactivar este comportamiento es agregar la siguiente configuración a tu configuración de ubicación.

proxy_set_header Authorization "";

Una futura versión del módulo puede hacer que este comportamiento sea una opción, pero esto debería ser una solución suficiente por ahora.

Si deseas habilitar las reglas de nombre local GSS para reescribir nombres de usuario, puedes especificar la opción auth_gss_map_to_local.

Delegación de credenciales

Las credenciales de usuario pueden ser delegadas a nginx utilizando la directiva auth_gss_delegate_credentials. Esta directiva habilitará la delegación no restringida si el usuario elige delegar sus credenciales. La delegación restringida (S4U2proxy) también puede ser habilitada utilizando la directiva auth_gss_constrained_delegation junto con la directiva auth_gss_delegate_credentials. Para especificar el nombre del archivo ccache para almacenar el ticket de servicio utilizado para la delegación restringida, establece la directiva auth_gss_service_ccache. De lo contrario, se utilizará el nombre de ccache por defecto.

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

Las credenciales delegadas se almacenarán dentro del directorio tmp del sistema. Una vez que la solicitud se complete, el archivo de credenciales será destruido. El nombre del archivo de credenciales se especificará dentro de la variable nginx $krb5_cc_name. El uso de la variable puede incluir pasarla a un programa fcgi utilizando la directiva fastcgi_param.

fastcgi_param KRB5CCNAME $krb5_cc_name;

La delegación restringida actualmente solo es compatible utilizando el esquema de autenticación negotiate y solo ha sido probada con MIT Kerberos (Usa bajo tu propio riesgo si usas Heimdal Kerberos).

Recaída a autenticación básica

El módulo recae en la autenticación básica por defecto si no se intenta ninguna negociación por parte del cliente. Si estás utilizando SPNEGO sin SSL, se recomienda desactivar la recaída a autenticación básica, ya que la contraseña se enviaría en texto plano. Esto se hace estableciendo auth_gss_allow_basic_fallback en el archivo de configuración.

auth_gss_allow_basic_fallback off

Estas opciones afectan el funcionamiento de la autenticación básica: * auth_gss_realm: nombre del reino Kerberos. Si esto se especifica, el reino se pasa solo a la variable nginx $remote_user si difiere de este valor por defecto. Para anular este comportamiento, establece auth_gss_format_full en 1 en tu configuración. * auth_gss_force_realm: Autenticar forzosamente utilizando el reino configurado en auth_gss_realm o el reino por defecto del sistema si auth_gss_realm no está configurado. Esto reescribirá $remote_user si el cliente proporcionó un reino diferente. Si auth_gss_format_full no está configurado, $remote_user no incluirá un reino incluso si uno fue especificado por el cliente.

Solución de problemas

Revisa los registros. Si ves una mención de NTLM, tu cliente está intentando conectarse utilizando NTLMSSP, que no es compatible y es inseguro.

Verifica que tienes un principal HTTP en tu keytab

Utilidades MIT Kerberos

$ KRB5_KTNAME=FILE:<ruta a tu keytab> klist -k

o

$ ktutil
ktutil: read_kt <ruta a tu keytab>
ktutil: list

Utilidades Heimdal Kerberos

$ ktutil -k <ruta a tu keytab> list

Obtén un principal HTTP

Si descubres que no tienes el principal de servicio HTTP, estás ejecutando en un entorno de Active Directory, y estás unido al dominio de tal manera que las herramientas de Samba funcionan correctamente

$ env KRB5_KTNAME=FILE:<ruta a tu keytab> net ads -P keytab add HTTP

Si estás ejecutando en un entorno kerberos diferente, probablemente puedas ejecutar

$ env KRB5_KTNAME=FILE:<ruta a tu keytab> krb5_keytab HTTP

Aumentar el tamaño máximo permitido del encabezado

En un entorno de Active Directory, el token SPNEGO en el encabezado de Autorización incluye información PAC (Privilege Access Certificate), que incluye todos los grupos de seguridad a los que pertenece el usuario. Esto puede hacer que el encabezado crezca más allá del límite por defecto de 8 kB y causar el siguiente mensaje de error:

400 Bad Request
Request Header Or Cookie Too Large

Por razones de rendimiento, la mejor solución es reducir el número de grupos a los que pertenece el usuario. Cuando esto es impráctico, también puedes optar por aumentar el tamaño del encabezado permitido estableciendo explícitamente el número y tamaño de los búferes de encabezado de Nginx:

large_client_header_buffers 8 32k;

Depuración

El módulo imprime todo tipo de información de depuración si nginx está compilado con la opción --with-debug, y la directiva error_log tiene un nivel debug.

NTLM

Ten en cuenta que el módulo no soporta NTLMSSP en Negotiate. NTLM, tanto v1 como v2, es un protocolo explotable y debe ser evitado cuando sea posible.

Windows

Para entornos KDC/AD de Windows, consulta la documentación aquí.

Ayuda

Si no puedes resolver las cosas, no dudes en abrir un problema en Github y haré lo posible por ayudarte.