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

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

Совместно с администраторами домена и инфраструктуры проверьте:

  1. DNS с рабочих мест и сервера Keycloak, доступность KDC по TCP/UDP 88 и синхронизацию времени.
  2. SPN HTTP/<HTTP_SERVICE_FQDN> зарегистрирован только на одной сервисной учётной записи. Дубликат SPN делает Kerberos-аутентификацию неработоспособной.
  3. Keytab соответствует principal, актуальной версии ключа и разрешённым типам шифрования. При смене пароля сервисной учётной записи keytab необходимо перевыпустить по регламенту домена.
  4. Reverse proxy передаёт WWW-Authenticate: Negotiate и Authorization: Negotiate, не записывая билеты в журналы.
  5. Подготовлены 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

  1. В realm itam откройте User Federation и нужный LDAP provider.
  2. В разделе 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 заранее проверьте уникальность сопоставления.

  1. Проверьте mapper kerberos-principal-attribute-mapper и сохраните настройки.

Kerberos integration

На иллюстрации параметры обезличены. Показанный 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-обмена.

  1. Откройте Authentication → Flows → browser и проверьте фактические значения.
  2. В Clients → itam-front → Authentication flow overrides убедитесь, что override не заменяет поток. Если override задан в вашей установке, проверяйте назначенный flow, а не только browser realm.
  3. Сохраните ветку Forms, включая Conditional OTP. Наличие Conditional OTP не означает обязательную MFA для всех пользователей.
  4. Если требуется строго разделить парольный и SSO-сценарии, создайте копии flow и назначьте их через клиентские overrides после тестирования. Не изменяйте общий flow ради одного клиента без проверки остальных.

Подготовьте браузер

  1. Используйте поддерживаемый браузер из раздела 3.01 и рабочее место с действующим доменным Kerberos-билетом.
  2. Разрешите Integrated Authentication только для <HTTP_SERVICE_FQDN>:
  3. Chromium, Edge, Яндекс Браузер — корпоративная политика AuthServerAllowlist;
  4. Firefox — network.negotiate-auth.trusted-uris.
  5. Не добавляйте wildcard-домены и все сайты в доверенные. Не включайте делегирование учётных данных, если оно не требуется отдельной архитектурой.
  6. Для проверки используйте обычный разрешённый профиль браузера: приватный режим может ограничивать Integrated Authentication.

Проверьте вход

  1. Сохраните рабочий административный вход без Kerberos.
  2. На подготовленном рабочем месте начните новый вход без существующей Keycloak-сессии.
  3. Убедитесь, что выполняется Negotiate challenge и открывается портал без повторного ввода пароля.
  4. Проверьте, что вошёл ожидаемый пользователь, его атрибуты и прикладные группы.
  5. Отдельно проверьте поведение без доменного билета и для пользователя вне Users DN.
  6. Проверьте обычный парольный вход и предусмотренную 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.