Настройка сквозной Kerberos-аутентификации (SSO)

В данном разделе описан порядок настройки беспарольного входа доменных пользователей Active Directory в веб-приложение SALT.BOX.

к сведению

Для настройки сквозной Kerberos-аутентификации необходимо, чтобы у Вас был настроен и работал LDAP-провайдер.
Порядок настройки LDAP-провайдера описан в разделе Интеграция Keycloak с Microsoft Active Directory.

Создание ключевого файла keytab

На контроллере домена создается связь веб-ресурса с доменной учетной записью службы и генерируется ключевой файл keytab.

1. Создайте в Active Directory сервисную учётную запись (например, svc-keycloak).
   Порядок создания и требования к сервисной учётной записи описаны в разделе Интеграция Keycloak с Microsoft Active Directory / Создание сервисной учётной записи в Microsoft Active Directory.

2. В свойствах созданного аккаунта на вкладке Учетная запись (Account) в списке параметров (Account options) обязательно включите поддержку шифрования:

   • This account supports Kerberos AES 128 bit encryption
   • This account supports Kerberos AES 256 bit encryption

3. Откройте командную строку от имени пользователя с правами администратора и выполните команду для создания keytab-файла:

   ktpass /out keycloak.keytab /princ HTTP/saltbox.saltbox.ru@SALTBOX.RU /mapuser svc-keycloak@SALTBOX.RU /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL /pass ВАШ_ПАРОЛЬ

   Пояснение параметров команды:

   Ключ	Пояснение	Значение
   /out	Имя выходного файла, в который записываются Kerberos-ключи	keycloak.keytab
   /princ	Kerberos-принципал. Задаёт имя службы, для которой создаётся keytab-файл	HTTP/saltbox.saltbox.ru@SALTBOX.RU — HTTP — класс службы (Service Class); — saltbox.saltbox.ru — имя узла, для которого зарегистрирована служба; — SALTBOX.RU — область Kerberos (realm), соответствующая домену Active Directory
   /mapuser	Учётная запись Active Directory, с которой связывается указанный Kerberos-принципал	svc-keycloak@SALTBOX.RU — svc-keycloak — учётная запись пользователя домена для управления службами Kerberos; — SALTBOX.RU — область Kerberos (realm), соответствующая домену Active Directory
   /crypto	Алгоритм шифрования Kerberos-ключа	AES256-SHA1
   /ptype	Тип Kerberos-принципала. KRB5_NT_PRINCIPAL — универсальный и рекомендуемый тип: имя принципала имеет общий формат (обычно вида имя_пользователя@ДОМЕН или сервис/имя_узла@ДОМЕН)	KRB5_NT_PRINCIPAL
   /pass *	Ключ с символом * после него вызывает интерактивный запрос пароля учётной записи для формирования Kerberos-ключей	пароль учётной записи svc-keycloak

   Параметры команды приведены в качестве примера, замените на соответствующие Вашему домену и серверу KeyCloak.

предупреждение

Для корректной работы KeyCloak с Active Directory рекомендуется указывать имя реалма (например, SALTBOX.RU) в верхнем регистре. DNS-имя узла указывается в нижнем регистре.
Используйте одинаковое написание имени реалма в команде ktpass, конфигурации Kerberos (файл krb5.conf) и настройках KeyCloak.

Перенос ключевого файла на сервер KeyCloak

к сведению

Ниже приведён способ копирования файла keycloak.keytab в случае, когда подсистема управления доступом KeyCloak развёрнута в Docker согласно инструкции по развёртыванию сервера SALT.BOX.

Подкаталог _identity каталога Compose-проекта SALT.BOX смонтирован в файловой системе контейнера KeyCloak по пути /etc/identity/.

Скопируйте файл keycloak.keytab с контроллера домена в подкаталог _identity.

осторожно

Доступ к keytab-файлу должен быть ограничен в операционной системе Docker-хоста, т. к. он содержит криптографические ключи Kerberos, позволяющие проходить аутентификацию от имени одной или нескольких учётных записей без ввода пароля.

В каталоге Compose-проекта SALT.BOX установите владельца, группу и права доступа к файлу:

sudo chown root:root ./_identity/keycloak.keytab
sudo chmod 600 ./_identity/keycloak.keytab

При монтировании подкаталога _identity в каталог /etc/identity/ контейнера KeyCloak владелец и права доступа к файлу будут спроецированы в целевую систему.

Настройка конфигурации Kerberos для KeyCloak

предупреждение

Системное время на хосте Linux, в контейнере KeyCloak и на контроллере домена Windows должно быть синхронизировано по UTC.
Допустимое расхождение определяется настройками Kerberos и по умолчанию обычно не должно превышать 5 минут.
При превышении этого порога Kerberos-аутентификация может завершиться ошибкой.

В подкаталоге _identity каталога Compose-проекта SALT.BOX создайте конфигурационный файл krb5.conf:

krb5.conf

[libdefaults]
    default_realm = SALTBOX.RU
    dns_lookup_realm = false
    dns_lookup_kdc = true
    rdns = false
    ticket_lifetime = 24h
    renew_lifetime = 7d
    forwardable = true
    default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
    default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
    permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
   
[realms]
    SALTBOX.RU = {
        kdc = dc-std-2025.saltbox.ru
        default_domain = saltbox.ru
    }
   
[domain_realm]
    .saltbox.ru = SALTBOX.RU
    saltbox.ru = SALTBOX.RU

Замените имя реалма и DNS-имена на соответствующие Вашему домену.

к сведению

В конфигурации Compose-проекта SALT.BOX через переменную окружения JAVA_OPTS_APPEND передаётся дополнительный параметр запуска JVM, в которой выполняется приложение Keycloak.
Параметр указывает путь к конфигурационному файлу Kerberos внутри контейнера KeyCloak: /etc/identity/krb5.conf.
Параметр задан явно, поскольку файл krb5.conf размещён не в стандартном расположении, используемом Java для поиска конфигурации Kerberos.

Настройка провайдера федерации в Keycloak

Настройка интеграции с Kerberos:

1. Перейдите в боковое меню Федерация пользователей (User Federation), откройте страницу настроек Вашего провайдера федерации (LDAP).

2. Убедитесь, что в поле Атрибут Username в LDAP (Username LDAP attribute) установлено значение userPrincipalName.

3. Перейдите в блок параметров Интеграция с Kerberos (Kerberos integration) и установите параметры в соответствии сс таблицей ниже:

   Параметр	Значение
   Разрешить аутентификацию Kerberos	ВКЛ
   Kerberos Realm	SALTBOX.RU значение, указанное при создании keytab-файла
   Основной сервер	HTTP/saltbox.saltbox.ru@SALTBOX.RU значение, указанное при создании keytab-файла
   KeyTab	/etc/identity/keycloak.keytab полный путь к ключевому файлу в контейнере
   Главный атрибут Kerberos	userPrincipalName
   Отладчик	ВЫКЛ
   Использовать Kerberos для аутентификации по паролю	ВЫКЛ

   Нажмите кнопку Сохранить (Save).

4. В верхней правой части страницы нажмите Действие (Action), выберите пункт Синхронизировать всех пользователей (Sync all users).
   Убедитесь, что во всплывающем сообщении о статусе синхронизации отсутствуют ошибки синхронизации пользователей.

Настройка области применения клиента (сервиса SALT.BOX)

1. В боковом меню KeyCloak выберите Клиенты (Clients), на открывшейся странице клиентов выберите сервис, обеспечивающий аутентификацию пользователей SALT.BOX, — saltbox_core.

2. На странице данных клиента перейдите на вкладку Области применения клиента (Client Scopes), выберите область (scope) saltbox_core-dedicated и откройте вкладку Область (Scope).

3. Убедитесь, что переключатель Полный доступ к областям (Full scope allowed) установлен в положение ВКЛ. Это гарантирует включение в JWT-токен, формируемый сервером KeyCloak для сервиса saltbox_core, всех необходимых параметров.

Настройка браузера для SSO-аутентификации

Чтобы веб-браузер автоматически передавал Kerberos-билеты веб-серверу при обращении к веб-интерфейсу SALT.BOX, добавьте адрес веб-сервера в список доверенных узлов веб-браузера:

1. Добавление доверенного сервера

   • Для Chromium-браузеров:
     Запустите командную оболочку cmd.exe от имени пользователя с правами локального администратора и выполните команду для добавления домена в групповую политику веб-браузера (настройка работает для Chromium-браузеров):

     reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\<ветка_политик_браузера>" /v "AuthServerAllowlist" /t REG_SZ /d "*.saltbox.ru" /f

     Значение ветка_политик_браузера:

     • для Яндекс.Браузера: YandexBrowser\HttpAuthSchemes
     • для Google Chrome: Google\Chrome
     • для Microsoft Edge: Microsoft\Edge

   • Для Mozilla Firefox:
     Firefox не использует параметр AuthServerAllowlist так же, как Chromium-браузеры.
     Для включения Kerberos-аутентификации настройте параметр network.negotiate-auth.trusted-uris:

     1. Откройте Firefox и перейдите на страницу about:config;
     2. Найдите параметр network.negotiate-auth.trusted-uris;
     3. Установите значение: *.saltbox.ru.

2. Контрольная проверка на клиенте (Для Chromium-браузеров)

   Откройте веб-браузер и перейдите на страницу:

   • для Яндекс.Браузера: browser://policy
   • для Google Chrome: chrome://policy
   • для Microsoft Edge: edge://policy

   В списке должна отобразиться активная политика AuthServerAllowlist с доверенным сервером *.saltbox.ru и статусом ОК.

3. Перед первым тестированием сквозной аутентификации сбросьте кэш Kerberos-билетов в Windows командой klist purge.

---

После выполнения всех шагов сквозная SSO-аутентификация будет работать автоматически: пользователь, вошедший в Windows под доменной учётной записью, сможет открывать веб-интерфейс SALT.BOX без повторного ввода логина и пароля.

Браузер будет автоматически передавать Kerberos-билет веб-серверу, а KeyCloak — выполнять аутентификацию пользователя на основании полученных данных.