3.05.03 Настройка Kerberos/SPNEGO SSO
Kerberos/SPNEGO позволяет Keycloak аутентифицировать пользователя по доменному билету браузера без повторного ввода пароля. LDAP используется для поиска учётной записи и её атрибутов. Успешная аутентификация не назначает прикладные права ITAM автоматически.
Сначала настройте LDAP provider, затем Kerberos и Browser flow. Режим страницы приложения описан в 3.05.02 Выбор режима авторизации.
Подготовьте параметры и доступы
| Обозначение | Что подготовить |
|---|---|
<KEYCLOAK_URL> |
Внешний HTTPS-адрес Keycloak, включая /kc, если используется |
<REALM> |
Realm приложения — itam, не master |
<KERBEROS_REALM> |
Kerberos realm организации, например EXAMPLE.ORG |
<HTTP_SERVICE_FQDN> |
Внешнее DNS-имя службы, к которой обращается браузер |
<HTTP_PRINCIPAL> |
HTTP/<HTTP_SERVICE_FQDN>@<KERBEROS_REALM> |
<KEYTAB_PATH> |
Путь к keytab внутри контейнера Keycloak |
Совместно с администраторами домена и инфраструктуры проверьте:
- DNS с рабочих мест и сервера Keycloak, доступность KDC по TCP/UDP 88 и синхронизацию времени.
- SPN
HTTP/<HTTP_SERVICE_FQDN>зарегистрирован только на одной сервисной учётной записи. Дубликат SPN делает Kerberos-аутентификацию неработоспособной. - Keytab соответствует principal, актуальной версии ключа и разрешённым типам шифрования. При смене пароля сервисной учётной записи keytab необходимо перевыпустить по регламенту домена.
- Reverse proxy передаёт
WWW-Authenticate: NegotiateиAuthorization: Negotiate, не записывая билеты в журналы. - Подготовлены Users DN, bind-учётная запись и защищённое LDAP-соединение по 3.05.01.
Выпуск и ротацию keytab выполняет администратор домена. ktpass не является диагностической командой: неправильное применение может изменить сопоставление SPN и ключи учётной записи. Не передавайте пароль открытым аргументом и не выбирайте -crypto ALL без проверки политики домена и поддержки Java.
Подключите Kerberos-файлы к контейнеру
Файлов на сервере недостаточно: keytab и krb5.conf должны быть доступны процессу Keycloak внутри контейнера. Добавьте в существующий список volumes сервиса keycloak, сохранив остальные mounts:
volumes:
- type: bind
source: "<KEYTAB_HOST_PATH>"
target: /run/secrets/http.keytab
read_only: true
bind:
create_host_path: false
- type: bind
source: "<KRB5_CONF_HOST_PATH>"
target: /etc/krb5.conf
read_only: true
bind:
create_host_path: false
В примере <KEYTAB_PATH> в настройках Keycloak — /run/secrets/http.keytab. Проверьте владельца и права чтения для процесса контейнера, а также SELinux/AppArmor. read_only не выдаёт отсутствующие права. Не включайте keytab в образ, документацию или репозиторий.
Проверьте наличие файлов без вывода их содержимого:
sudo docker compose -f /opt/itam/docker-compose.yml --env-file /opt/itam/.env exec -T keycloak \
ls -l /run/secrets/http.keytab /etc/krb5.conf
После изменения volumes пересоздайте сервис командой up -d keycloak, а не restart:
sudo docker compose -f /opt/itam/docker-compose.yml --env-file /opt/itam/.env up -d keycloak
Настройте Kerberos в LDAP provider
- В realm
itamоткройте User Federation и нужный LDAP provider. - В разделе Kerberos integration заполните:
| Параметр | Значение |
|---|---|
| Allow Kerberos authentication | ON только у provider, обслуживающего этот домен |
| Kerberos realm | <KERBEROS_REALM>, например EXAMPLE.ORG |
| Server principal | HTTP/<HTTP_SERVICE_FQDN>@<KERBEROS_REALM> |
| KeyTab | /run/secrets/http.keytab |
| Use Kerberos for password authentication | OFF, если отдельная проверка введённого пароля через Kerberos не требуется |
| Kerberos principal attribute | Для AD обычно userPrincipalName; проверьте соответствие UPN пользователя |
| Debug | OFF; включайте только на согласованное время диагностики |
Не вводите полный HTTP principal в поле Kerberos realm. Realm Keycloak и Kerberos realm — разные параметры.
При userPrincipalName пользователь ищется по полному principal user@EXAMPLE.ORG, что помогает различать одинаковые короткие логины. Если атрибут не задан, используется имя без Kerberos realm. Для нескольких доменов или cross-realm trust заранее проверьте уникальность сопоставления.
- Проверьте mapper
kerberos-principal-attribute-mapperи сохраните настройки.

На иллюстрации параметры обезличены. Показанный Debug = ON предназначен только для диагностики.
Проверьте Browser flow
Одного включения Kerberos в LDAP provider недостаточно: исполнитель Kerberos (auth-spnego) должен быть разрешён в Browser flow, который фактически использует клиент.
В комплекте у itam-front нет клиентского override. Используется общий flow browser realm:
| Этап | Requirement |
|---|---|
| Cookie | ALTERNATIVE |
| Kerberos | ALTERNATIVE |
| Identity Provider Redirector | ALTERNATIVE |
| Forms | ALTERNATIVE |
Этот поток допускает SSO и парольный fallback через один клиент. ALTERNATIVE не делает Kerberos обязательным для каждого входа: при отсутствии пригодного билета поток может перейти к форме. Существующая SSO-сессия может быть обслужена этапом Cookie без нового Kerberos-обмена.
- Откройте Authentication → Flows → browser и проверьте фактические значения.
- В Clients → itam-front → Authentication flow overrides убедитесь, что override не заменяет поток. Если override задан в вашей установке, проверяйте назначенный flow, а не только
browserrealm. - Сохраните ветку Forms, включая Conditional OTP. Наличие Conditional OTP не означает обязательную MFA для всех пользователей.
- Если требуется строго разделить парольный и SSO-сценарии, создайте копии flow и назначьте их через клиентские overrides после тестирования. Не изменяйте общий flow ради одного клиента без проверки остальных.
Подготовьте браузер
- Используйте поддерживаемый браузер из раздела 3.01 и рабочее место с действующим доменным Kerberos-билетом.
- Разрешите Integrated Authentication только для
<HTTP_SERVICE_FQDN>: - Chromium, Edge, Яндекс Браузер — корпоративная политика
AuthServerAllowlist; - Firefox —
network.negotiate-auth.trusted-uris. - Не добавляйте wildcard-домены и все сайты в доверенные. Не включайте делегирование учётных данных, если оно не требуется отдельной архитектурой.
- Для проверки используйте обычный разрешённый профиль браузера: приватный режим может ограничивать Integrated Authentication.
Проверьте вход
- Сохраните рабочий административный вход без Kerberos.
- На подготовленном рабочем месте начните новый вход без существующей Keycloak-сессии.
- Убедитесь, что выполняется Negotiate challenge и открывается портал без повторного ввода пароля.
- Проверьте, что вошёл ожидаемый пользователь, его атрибуты и прикладные группы.
- Отдельно проверьте поведение без доменного билета и для пользователя вне Users DN.
- Проверьте обычный парольный вход и предусмотренную MFA.
Не сохраняйте в отчётах заголовки Authorization, cookies, keytab, билеты и токены.
Диагностика
| Симптом | Что проверить |
|---|---|
| Сразу отображается форма без Negotiate | Browser flow и клиентский override, политику браузера, наличие прежней Cookie-сессии |
Повторяющиеся 401 / Negotiate |
SPN внешнего FQDN, дубликаты SPN, keytab и версию ключа, DNS, время, KDC, заголовки proxy |
| Kerberos принят, но пользователь не найден | Users DN, Search Scope, userPrincipalName, совпадения логинов, выбранный provider |
| Пользователь не импортируется | LDAPS/StartTLS и доверие CA, bind-права, обязательные атрибуты, фильтры и пагинацию |
| Вход есть, но разделы ITAM недоступны | Группы безопасности и роли ITAM |
| SSO работает только в старом окне | Прежняя Keycloak-сессия, обслуженная Cookie без нового Kerberos-обмена |
В команде запуска Keycloak комплекта могут присутствовать -Dsun.security.krb5.debug=true, -Dsun.security.spnego.debug=true и -Dsun.security.jgss.debug=true. После диагностики удалите эти параметры и пересоздайте сервис, чтобы не записывать избыточные сведения в журналы.
Общие сведения приведены в Keycloak Server Administration Guide — Kerberos.
Результат: SSO и предусмотренный fallback проверены на отдельных рабочих местах, пользователь корректно сопоставлен с записью ITAM.