spnego-http-auth: Модуль Nginx для HTTP SPNEGO аутентификации
Установка
Вы можете установить этот модуль в любой дистрибутив на базе 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.1.3, выпущенный 12 мая 2025 года.
Этот модуль добавляет поддержку 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 в 1 в вашей конфигурации.
* 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), которая включает все группы безопасности, к которым принадлежит пользователь. Это может привести к тому, что заголовок превысит лимит по умолчанию в 8 кБ и вызовет следующее сообщение об ошибке:
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, и я постараюсь вам помочь.
GitHub
Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-spnego-http-auth.