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

3.05.01 Настройка LDAP в Keycloak

Перед началом

Подготовьте у администратора каталога:

  • адрес LDAP/LDAPS и доверенный сертификат для защищённого соединения;
  • Users DN — область поиска пользователей;
  • bind-учётную запись с правами только на чтение необходимых записей;
  • атрибут логина и стабильный уникальный идентификатор записи;
  • список атрибутов, которые нужно передать в ITAM;
  • правила обработки удалённых, заблокированных и перемещённых учётных записей.

Раздел описывает realm itam. Не используйте realm master для пользователей приложения.

Создайте LDAP provider

  1. Откройте административную консоль Keycloak и выберите realm itam.
  2. Перейдите в User Federation и добавьте provider типа LDAP.
  3. Заполните параметры по типу каталога.
Параметр Active Directory FreeIPA / Red Hat Directory Server
Vendor Active Directory Red Hat Directory Server, если этот профиль соответствует серверу
Edit Mode READ_ONLY для типового импорта без записи в каталог Аналогично
Username LDAP attribute sAMAccountName Обычно uid; проверьте фактический атрибут
RDN LDAP attribute cn Должен соответствовать RDN записей, часто uid
UUID LDAP attribute objectGUID Для RHDS обычно nsuniqueid; проверьте доступность и неизменность
User Object Classes user По схеме, например person, organizationalPerson, inetOrgPerson
Connection URL ldaps://<LDAP_HOST>:636 или ldap://<LDAP_HOST>:389 со StartTLS Аналогично
Users DN DN области поиска пользователей DN области поиска пользователей
Search Scope One Level — один уровень; Subtree — с вложенными подразделениями Аналогично
Bind Type simple вместе с LDAPS или StartTLS Аналогично
Bind DN / Bind Credential DN и пароль bind-учётной записи Аналогично
Import Users ON ON

Не используйте gidNumber как UUID пользователя: это идентификатор группы и он не уникален для пользователя. uidNumber применяйте только после подтверждения его неизменности и уникальности; предпочтителен UUID записи каталога. Не меняйте UUID LDAP attribute после импорта без проверки связей существующих пользователей.

  1. Для LDAPS или StartTLS поместите корневой сертификат удостоверяющего центра в формате PEM в /opt/itam/kctrust/ на сервере. Каталог подключён к /opt/keycloak/conf/truststores контейнера Keycloak. Установите Use Truststore SPI = always и перезапустите Keycloak:
sudo docker compose -f /opt/itam/docker-compose.yml --env-file /opt/itam/.env restart keycloak
  1. Нажмите Test connection, затем Test authentication для тестовой учётной записи. Эти действия обращаются к каталогу; выполняйте их с согласованными тестовыми реквизитами.
  2. Нажмите Save.

Сочетание ldap://, simple и выключенного StartTLS передаёт bind-пароль и LDAP-трафик без TLS-защиты. Для продуктивной установки используйте LDAPS или StartTLS. HTTPS портала не защищает отдельное соединение Keycloak с каталогом.

Выберите Edit Mode

  • READ_ONLY — рекомендуемый режим, если каталог является источником данных. Keycloak не изменяет сопоставленные атрибуты и пароль в каталоге.
  • UNSYNCED — изменения сохраняются локально в Keycloak и не записываются в LDAP автоматически.
  • WRITABLE — изменения записываются в каталог при соответствующих правах и mappers. Используйте только при явной необходимости и после проверки на тестовых записях.

В файле импорта комплекта приведён пример UNSYNCED. Для новой установки без записи в каталог выберите READ_ONLY до синхронизации и проверьте mappers. При последующей смене Edit Mode настройки существующих mappers автоматически не перестраиваются.

Не выдавайте bind-учётной записи права администратора домена. Для чтения LDAP и использования ранее выпущенного Kerberos keytab такие права не требуются.

Проверьте сопоставление атрибутов

Откройте Mappers в созданном provider. Для Active Directory проверьте mapper username: LDAP Attribute должен быть sAMAccountName либо другим согласованным атрибутом логина.

Типовые сопоставления:

LDAP Attribute User Model Attribute
sAMAccountName (AD) или uid (FreeIPA/RHDS) username
givenName firstName
sn lastName
mail email
title position
middleName middleName
telephoneNumber telephoneNumber
mobile mobile
department divisionName
company counterpartyName
l city

Прикладные атрибуты manager, maintenanceCalendar, employeeId, type и permissions добавляйте только после подтверждения их источника и формата. Не делайте расширенные атрибуты обязательными, если они заполнены не у всех пользователей: синхронизация таких записей может завершаться ошибкой.

LDAP mapper и OIDC protocol mapper выполняют разные задачи. Первый заполняет атрибут пользователя Keycloak, второй передаёт значение в токен. Не создавайте hardcoded mappers type или permissions для автоматической выдачи одинаковых прав всем пользователям. Группы AD не превращаются в группы безопасности ITAM без отдельной настройки; прикладные права назначайте и проверяйте в ITAM.

LDAP: подключение и bind-аутентификация

LDAP: область поиска и сопоставление атрибутов

На иллюстрациях реквизиты заменены обозначениями; переключатели показывают пример интерфейса, а не готовый профиль безопасности.

Выполните синхронизацию

  1. Сначала выполните Synchronize changed users для ограниченной проверки либо Synchronize all users, если требуется первичный импорт всей области.
  2. Просмотрите результат и журнал Keycloak.
  3. Найдите тестового пользователя в Users и проверьте логин, email и сопоставленные атрибуты.
  4. В ITAM откройте «Пользователи и роли», дождитесь появления пользователя и назначьте группы доступа.
  5. Проверьте вход, разрешённые разделы и операции.

Параметры Full Sync Period и Changed Users Sync Period задаются в секундах. Значение -1 отключает соответствующую периодическую синхронизацию; именно так заданы периоды в импорте комплекта. Для автоматической синхронизации задайте положительные интервалы, учитывая количество записей и нагрузку на каталог. Наличие расписания не подтверждает успешность каждого запуска — контролируйте журналы.

Перед изменением Users DN, Search Scope или фильтров оцените влияние на уже импортированные записи. Сужение области поиска не должно автоматически рассматриваться как безопасный способ удаления пользователей. Опцию Remove invalid users during searches применяйте только после проверки последствий на тестовом контуре.

Если требуется Kerberos

Kerberos включается только у provider, обслуживающего соответствующий домен. Не включайте его одновременно у нескольких провайдеров без проверки одинаковых логинов и областей поиска. SPN, keytab, Browser flow и подготовка браузера описаны в 3.05.03 Настройка Kerberos/SPNEGO SSO.

Общие сведения приведены в Keycloak Server Administration Guide — LDAP.

Результат: защищённое подключение сохранено, тестовый пользователь синхронизирован, вход и прикладные права проверены.