spnego-http-auth: Модуль NGINX для HTTP SPNEGO аутентификации
Требует подписку Pro плана (или выше) на GetPageSpeed NGINX Extras.
Установка
Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:
- RedHat Enterprise Linux 7, 8, 9 и 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 и 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
Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:
load_module modules/ngx_http_auth_spnego_module.so;
Этот документ описывает nginx-module-spnego-http-auth v1.2.0, выпущенный 14 февраля 2026 года.
Этот модуль добавляет поддержку SPNEGO в nginx(http://nginx.org). В настоящее время он поддерживает только аутентификацию Kerberos через GSSAPI.
Предварительные требования
Аутентификация была протестирована как минимум с следующими версиями:
- Nginx 1.2 до 1.15
- Internet Explorer 8 и выше
- Firefox 10 и выше
- Chrome 20 и выше
- Curl 7.x (GSS-Negotiate), 7.x (SPNEGO/fbopenssl)
Библиотека kerberos, используемая для этих тестов, была MIT KRB5 v1.12.
Справочник по конфигурации
Вы можете настроить GSS аутентификацию на уровне конкретного местоположения и/или глобально:
Эти параметры обязательны.
* auth_gss: включить/выключить, для удобства отключения, оставляя другие параметры в конфигурационном файле.
* auth_gss_keytab: абсолютный путь к файлу keytab, содержащему учетные данные службы.
Эти параметры ДОЛЖНЫ быть указаны ТОЛЬКО в том случае, если у вас есть keytab, содержащий привилегированные принципы. В большинстве случаев вы не должны помещать их в конфигурационный файл, так как gss_accept_sec_context сделает все правильно.
* auth_gss_realm: имя Kerberos области. Если это указано, область передается в переменную nginx $remote_user только в том случае, если она отличается от этого значения по умолчанию. Чтобы переопределить это поведение, установите auth_gss_format_full в on в вашей конфигурации.
* auth_gss_service_name: имя сервисного принципала, используемое при получении учетных данных.
Если вы хотите авторизовать только определенный набор принципалов, вы можете использовать директиву auth_gss_authorized_principal. Синтаксис конфигурации поддерживает несколько записей, по одной на строку.
auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal <primary2>@<realm>
Принципы также могут быть авторизованы с использованием регулярного выражения через директиву auth_gss_authorized_principal_regex. Эта директива может использоваться вместе с директивой auth_gss_authorized_principal.
auth_gss_authorized_principal <primary1>@<realm>
auth_gss_authorized_principal_regex ^(<primary2>)/(<instance>)@<realm>$
Заголовок удаленного пользователя в nginx может быть установлен только с помощью базовой аутентификации. Таким образом, этот модуль устанавливает фиктивный заголовок базовой аутентификации, который достигнет вашего бэкенд-приложения для установки этого заголовка/переменной nginx. Самый простой способ отключить это поведение - добавить следующую конфигурацию в вашу конфигурацию местоположения.
proxy_set_header Authorization "";
Будущая версия модуля может сделать это поведение опциональным, но на данный момент это должно быть достаточным обходным решением.
Если вы хотите включить правила локальных имен GSS для переименования имен пользователей, вы можете указать параметр auth_gss_map_to_local.
Делегирование учетных данных
Учетные данные пользователя могут быть делегированы в nginx с помощью директивы auth_gss_delegate_credentials. Эта директива позволит осуществлять неконтролируемое делегирование, если пользователь решит делегировать свои учетные данные. Контролируемое делегирование (S4U2proxy) также может быть включено с помощью директивы auth_gss_constrained_delegation вместе с директивой auth_gss_delegate_credentials. Чтобы указать имя файла ccache для хранения служебного билета, используемого для контролируемого делегирования, установите директиву auth_gss_service_ccache. В противном случае будет использоваться имя ccache по умолчанию.
auth_gss_service_ccache /tmp/krb5cc_0;
auth_gss_delegate_credentials on;
auth_gss_constrained_delegation on;
Делегированные учетные данные будут храниться в временной директории системы. После завершения запроса файл учетных данных будет уничтожен. Имя файла учетных данных будет указано в переменной nginx $krb5_cc_name. Использование переменной может включать передачу ее в программу fcgi с помощью директивы fastcgi_param.
fastcgi_param KRB5CCNAME $krb5_cc_name;
Контролируемое делегирование в настоящее время поддерживается только с использованием схемы аутентификации negotiate и было протестировано только с MIT Kerberos (используйте на свой страх и риск, если используете Heimdal Kerberos).
Запасной вариант базовой аутентификации
Модуль по умолчанию переходит на базовую аутентификацию, если клиент не пытается провести переговоры. Если вы используете SPNEGO без SSL, рекомендуется отключить запасной вариант базовой аутентификации, так как пароль будет отправлен в открытом виде. Это делается путем установки auth_gss_allow_basic_fallback в конфигурационном файле.
auth_gss_allow_basic_fallback off
Эти параметры влияют на работу базовой аутентификации:
* auth_gss_realm: имя Kerberos области. Если это указано, область передается в переменную nginx $remote_user только в том случае, если она отличается от этого значения по умолчанию. Чтобы переопределить это поведение, установите auth_gss_format_full в 1 в вашей конфигурации.
* auth_gss_force_realm: Принудительная аутентификация с использованием области, настроенной в auth_gss_realm, или области по умолчанию системы, если auth_gss_realm не установлена. Это перепишет $remote_user, если клиент предоставил другую область. Если auth_gss_format_full не установлен, $remote_user не будет включать область, даже если она была указана клиентом.
Устранение неполадок
Проверьте журналы. Если вы видите упоминание о NTLM, ваш клиент пытается подключиться с использованием NTLMSSP, что не поддерживается и небезопасно.
Убедитесь, что у вас есть HTTP принципал в вашем keytab
Утилиты MIT Kerberos
$ KRB5_KTNAME=FILE:<path to your keytab> klist -k
или
$ ktutil
ktutil: read_kt <path to your keytab>
ktutil: list
Утилиты Heimdal Kerberos
$ ktutil -k <path to your keytab> list
Получите HTTP принципал
Если вы обнаружите, что у вас нет сервисного принципала HTTP, вы работаете в среде Active Directory и привязаны к домену, так что инструменты Samba работают правильно:
$ env KRB5_KTNAME=FILE:<path to your keytab> net ads -P keytab add HTTP
Если вы работаете в другой среде kerberos, вы можете запустить
$ env KRB5_KTNAME=FILE:<path to your keytab> krb5_keytab HTTP
Увеличьте максимальный допустимый размер заголовка
В среде Active Directory токен SPNEGO в заголовке Authorization включает информацию PAC (Privilege Access Certificate), которая содержит все группы безопасности, к которым принадлежит пользователь. Это может привести к тому, что заголовок превысит предельный размер 8kB и вызовет следующее сообщение об ошибке:
400 Bad Request
Request Header Or Cookie Too Large
По соображениям производительности лучшее решение - уменьшить количество групп, к которым принадлежит пользователь. Когда это невозможно, вы также можете выбрать увеличение допустимого размера заголовка, явно установив количество и размер буферов заголовков Nginx:
large_client_header_buffers 8 32k;
Отладка
Модуль выводит всевозможную отладочную информацию, если nginx скомпилирован с опцией --with-debug, и директива error_log имеет уровень debug.
NTLM
Обратите внимание, что модуль не поддерживает NTLMSSP в Negotiate. NTLM, как v1, так и v2, является уязвимым протоколом и должен избегаться, где это возможно.
Windows
Для сред KDC/AD Windows смотрите документацию здесь.
Помощь
Если вы не можете разобраться, пожалуйста, не стесняйтесь открыть проблему на Github, и я постараюсь помочь вам.