Перейти к содержанию

spnego-http-auth: Модуль Nginx для аутентификации HTTP SPNEGO

Установка для Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-spnego-http-auth, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-spnego-http-auth
Показать дистрибутивы и архитектуры 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

Этот модуль добавляет поддержку 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).

Резервное копирование базовой аутентификации

По умолчанию модуль переходит к базовой аутентификации, если клиент не пытается выполнитьNegotiation. Если вы используете 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:<путь к вашему keytab> klist -k

или

$ ktutil
ktutil: read_kt <путь к вашему keytab>
ktutil: list

Утилиты Heimdal Kerberos

$ ktutil -k <путь к вашему keytab> list

Получите HTTP принципал

Если вы обнаружите, что у вас нет серверного принципала HTTP, вы работаете в среде Active Directory и связаны с доменом таким образом, чтобы инструменты Samba работали корректно:

$ env KRB5_KTNAME=FILE:<путь к вашему keytab> net ads -P keytab add HTTP

Если вы работаете в другой среде Kerberos, вы, вероятно, можете выполнить

$ env KRB5_KTNAME=FILE:<путь к вашему 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, и я постараюсь помочь вам.