Настройка сквозной 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.

1. Скопируйте файл keycloak.keytab на Docker-хост с запущенным проектом SALT.BOX.

2. Скопируйте файл keycloak.keytab с Docker-хоста в каталог /etc контейнера KeyCloak:

   docker cp <полный_путь_к_ключевому_файлу_в_хост-системе> <ID_контейнера_keycloak>:/etc/keycloak.keytab

3. Выполните команды для установки прав доступа к ключевому файлу «только для владельца»:

   docker exec -it <ID_контейнера_keycloak> bash -c 'chown root:root /etc/keycloak.keytab'
   docker exec -it <ID_контейнера_keycloak> bash -c 'chmod 600 /etc/keycloak.keytab'

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

ВНИМАНИЕ

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

1. Подключитесь к контейнеру KeyCloak и запустите командную оболочку от имени пользователя root:

   docker exec -it <ID_контейнера_keycloak> bash

2. Создайте в контейнере конфигурационный файл /etc/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-имена на соответствующие Вашему домену.

Настройка провайдера федерации в 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/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 — выполнять аутентификацию пользователя на основании полученных данных.