Синхронизация с каталогом LDAP

LDAP (Lightweight Directory Access Protocol) — это протокол прикладного уровня для доступа к службе каталогов.

Служба каталогов (каталоги LDAP) — это система с иерархической структурой для хранения данных в формате "ключ-значение". Обычно службы каталогов используют для хранения информации об организации, её активах и пользователях. Существуют различные реализации каталогов LDAP. Например, ALD Pro, OpenLDAP и FreeIPA для Linux, Microsoft Active Directory для Windows и т.д.

Вы можете настроить синхронизацию платформы c одним или несколькими каталогами LDAP. Тогда учётные записи пользователей из каталогов будут автоматически создаваться в платформе. При настройке синхронизации задаётся соответствие DN-групп LDAP ролям в платформе. Для каждой роли VMmanager можно настроить синхронизацию с одной или несколькими DN-группами.

Логика работы

Платформа запускает синхронизацию с каталогами LDAP с периодичностью, заданной в настройках. При синхронизации платформа подключается с заданными параметрами к каталогу LDAP и получает список пользователей. Информация о пользователях из каталога LDAP более приоритетна по сравнению с информацией в платформе.

Правила синхронизации:

1. Если у пользователя в каталоге LDAP не указан email, его учётная запись не будет использована при синхронизации. 
   Правило актуально, если синхронизация была настроена в платформе версии ниже 2025.10.1 либо не была выполнена миграция на новую схему имён пользователей. Подробнее см. в разделе Синхронизация с несколькими каталогами LDAP.
2. Если пользователь Active Directory не входит в группу Users, его учётная запись не будет использована при синхронизации.
3. Если пользователя из каталога LDAP нет в платформе, платформа создаст учётную запись с данными из LDAP.
4. Если пользователь из каталога LDAP уже создан в платформе, то платформа изменит источник учётной записи пользователя с локального на LDAP. После этого пользователь сможет авторизоваться в платформе с email и паролем из LDAP. Пароль пользователя будет храниться в LDAP и не запишется в БД платформы. Администратор не сможет изменить пароль пользователя средствами платформы.
   Пример

   Например, в платформе создана учётная запись с именем admin@example.com и паролем secret1. В LDAP есть учётная запись с именем admin@example.com и паролем secret2. После синхронизации пользователь admin@example.com сможет авторизоваться в платформе только с паролем secret2.
5. Платформа не изменяет уровень учетной записи на данные из LDAP. Независимо от того, в какой группе находится учётная запись в LDAP, уровень учётной записи задается в платформе в настройках синхронизации с LDAP (соответствие DN-группы из LDAP роли в платформе).
6. Если администратор удалит из платформы пользователя, созданного при синхронизации с LDAP, платформа создаст этого пользователя при следующей синхронизации.
7. Если пользователь будет удалён из каталога LDAP, платформа установит для учётной записи статус "Заблокирован". Такой пользователь не сможет авторизоваться в платформе.
8. Если пользователь будет заблокирован в каталоге LDAP, платформа установит для него статус "Заблокирован в LDAP". Такой пользователь не сможет авторизоваться в платформе.

Синхронизация с несколькими каталогами LDAP

Начиная с версии VMmanager 2025.10.1 платформа поддерживает синхронизацию с несколькими каталогами LDAP. 

До версии 2025.10.1 в качестве имени пользователя использовался атрибут mail (адрес электронной почты) из LDAP. Начиная с версии 2025.10.1 имя пользователя формируется по схеме username@domain, где:

• username — логин пользователя в LDAP:
  • для стандартной реализации LDAP и FreeIPA — атрибут uid;
  • для Active Directory — атрибут sAMAccountName;
• domain — домен сервера LDAP.

Например, для DN-записи LDAP вида uid=admin,cn=users,cn=accounts,dc=example,dc=com будет создано имя пользователя admin@example.com.

Если в платформе версии ниже 2025.10.1 уже была настроена синхронизация с LDAP и нужно подключить ещё один каталог, возможны проблемы с корректным определением имён пользователей. Чтобы исключить эти проблемы, выполните миграцию на новую схему имени пользователя. Для миграции выполните через утилиту curl или Swagger API-запрос:

POST /auth/v4/ldap/{ldap_id}/migrate

Пояснения:

• {ldap_id} — id существующего подключения к LDAP. Отображается в разделе Синхронизация с LDAP в колонке id.

В процессе миграции все существующие пользователи из LDAP будут переименованы по новой схеме.

Подготовка

Перед синхронизацией рекомендуем создать в платформе учётную запись администратора, логин и домен которой отсутствуют в LDAP. Это поможет восстановить доступ к платформе, если после синхронизации учётная запись администратора по каким-то причинам окажется заблокированной.

Если на сервере с LDAP самоподписанный SSL-сертификат

Подключение к LDAP завершится с ошибкой, если требуется использовать SSL-соединение, а на сервере установлен самоподписанный SSL-сертификат. Чтобы ошибки подключения не возникало, выполните следующие действия перед настройкой синхронизации:

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.

2. Создайте директорию для конфигурации LDAP: 

   mkdir /opt/ispsystem/ldap/

3. Определите версию ОС внутри контейнера с LDAP: 

   docker inspect auth | grep docker-registry

   Версия ОС будет указана в последнем сегменте вывода. Пример вывода команды для контейнера с AlmaLinux 8.9: 

   "Image": "docker-registry.ispsystem.com/ispsystem/experimental/auth/alma:8.9"

4. Для контейнера LDAP с ОС Debian:

   1. Создайте в директории /opt/ispsystem/ldap/ файл ldap.conf с содержимым: 

      TLS_CACERT  /etc/ssl/certs/ca-certificates.crt
      TLS_REQCERT never

   2. Создайте файл патча /opt/ispsystem/ldap.yaml с содержимым: 

      version: "3.5"
      services:
        auth_back4:
          volumes:
          - /opt/ispsystem/ldap/:/etc/ldap/

5. Для контейнера LDAP с ОС AlmaLinux:

   1. Создайте в директории /opt/ispsystem/ldap/ файл ldap.conf с содержимым:

      TLS_CACERT    /etc/ssl/certs/ca-bundle.crt   
      TLS_REQCERT never

   2. Создайте файл патча /opt/ispsystem/ldap.yaml с содержимым: 

      version: "3.5"
      services:
        auth_back4:
          volumes:
          - /opt/ispsystem/ldap/:/etc/openldap/

6. Примените патч для сервиса LDAP: 

   vm add-patch -p=LDAP -f /opt/ispsystem/ldap.yaml

vm remove-patch -p=LDAP

Настройка синхронизации

Для управления синхронизацией с LDAP нажмите в правом меню значок   → Синхронизация с LDAP.

Интерфейс раздела

Создание подключения

Чтобы создать подключение к LDAP, нажмите кнопку Добавить подключение и укажите его настройки:

1. Выберите реализацию каталога LDAP:
   • LDAP — стандартная реализация службы каталогов;
   • Active Directory;
   • FreeIPA.
     
     Для синхронизации с ALD Pro выберите FreeIPA.
2. Укажите настройки подключения:
   1. Base DN — объект каталога, с которого начинается поиск. Например, для каталога example.com укажите dc=example,dc=com.
   2. Для подключения по SSL включите опцию Использовать SSL для подключения.
   3. Адрес основного сервера.
   4. Порт подключения.
   5. Bind DN — уникальное имя для аутентификации. Вы можете указать имя в формате name@example.com или cn=name,ou=group,dc=example,dc=com.
   6. Пароль.
   7. Для стандартной реализации LDAP укажите:
      1. Users DN — параметр для поиска и загрузки пользователей. Например, ou=users.
         
      2. Groups DN — параметр для поиска и загрузки групп пользователей. Например, ou=groups.
      3. Groupname attribute — атрибут для загрузки имени группы. Например, CN или memberof.
      4. E-mail attribute — атрибут для загрузки адреса электронной почты пользователя. Например, mail.
   8. Укажите произвольное Примечание.
      
3. Нажмите Далее. Платформа проверит подключение к каталогу LDAP с указанными параметрами.
4. Выберите, какие DN группы будут соответствовать каждой Роли в платформе. Чтобы добавить правило, нажмите кнопку Добавить группу. Чтобы удалить правило, нажмите значок .
5. Чтобы платформа выполняла синхронизацию по расписанию:
   1. Включите опцию Синхронизировать пользователей автоматически.
   2. Выберите параметры расписания:
      • Каждый час;
      • Ежедневно → выберите время;
      • Еженедельно → выберите день недели → выберите время;
      • произвольное время в формате cron → укажите Команду для cron. Например, 15 10 * * 0 — синхронизировать по воскресеньям в 10:15 или 00 12 1,16 * * — синхронизировать по 1-м и 16-м числам месяца в 12:00.
6. Чтобы проверить, какие пользователи будут синхронизированы, нажмите кнопку Загрузить список пользователей для синхронизации. Список содержит имена пользователей, их роли и информацию о том, созданы ли такие пользователи в платформе.
   
7. Нажмите кнопку Начать синхронизацию. Платформа запустит процесс синхронизации. Время синхронизации зависит от количества пользователей в LDAP и может занять несколько минут.

Управление подключениями

Управление подключением выполняется через меню   в строке с подключением. Возможные действия:

• Редактировать — перейти в карточку подключения. Для выполнения этого действия вы также можете нажать на название подключения в таблице. В карточке подключения вы можете изменить его настройки и правила синхронизации;
• Синхронизировать — выполнить повторную синхронизацию;
• Примечание — изменить примечание;
• Удалить.

Авторизация пользователей

Процесс авторизации пользователей зависит от количества каталогов LDAP, с которыми синхронизирована платформа:

• с одним каталогом или отсутствует — пользователь вводит имя в формате username@domain и пароль;
  
• с двумя и более каталогами — пользователь вводит имя в формате username или username@domain, выбирает каталог LDAP и вводит пароль.
  

Диагностика

Взаимодействие с LDAP выполняет сервис auth. Лог-файлы синхронизации хранятся на сервере с платформой в stdout контейнера auth. 

Чтобы увидеть детальную информацию о работе LDAP:

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
2. Установите для контейнера auth уровень логирования DEBUG:

   sudo docker exec -it vm_box curl -k 'http://input:1500/auth/v4/internal/settings/log/level' -H 'internal-auth: on' -d "debug"