Настройка синхронизации с Active Directory (AD LDAP / OpenLDAP)
Инструкция для администратора UnSpot и администратора каталога: как подключить синхронизацию сотрудников из локального Active Directory или OpenLDAP, какие поля перенести и как ограничить выборку. Подключение выполняется в разделе Настройка → Интеграции → Синхронизации. Настраивать интеграции могут роли Владелец и Администратор интеграций. Как устроен сам обмен и что уходит из каталога — в парной статье «Синхронизация пользователей с Active Directory (AD LDAP / OpenLDAP): как устроена»; её же передают службе информационной безопасности на согласование.
Что понадобится
- Роль в UnSpot: Владелец или Администратор интеграций.
- Сетевой доступ: контроллер домена должен принимать входящие подключения с адресов UnSpot на порт LDAP или LDAPS. Без этого форма не сохранится — UnSpot проверяет соединение перед записью настроек.
- Сервисная учётная запись в каталоге с правами только на чтение объектов пользователей, групп и подразделений.
- DN контейнера, от которого искать сотрудников.
- Свободный слот синхронизации: одновременно может быть подключён только один способ — AD LDAP, OpenLDAP, Entra ID или Google Workspace. Если подключён другой, сначала отключите его.
Шаг 1. Параметры подключения
Нажмите «Подключить» в карточке AD LDAP — откроется форма «Настройки синхронизации». Заполните блок «Параметры подключения»:
| Поле | Что указать |
|---|---|
| Хост | Сетевой адрес сервера каталога с префиксом протокола — ldap:// или ldaps://. Форма не примет адрес без префикса. Например: ldaps://dc01.mycompany.ru |
| DN | Отличительное имя контейнера, от которого искать пользователей. Пример из формы: CN=Users, DC=mycompany, DC=ru. Поле обязательное: искать от корня каталога нельзя |
| Порт | Подставляется 389 — и для ldap://, и для ldaps://. Если подключаетесь по LDAPS, замените значение на 636 вручную. Нестандартный порт указывайте фактический |
| Логин | Учётная запись, под которой UnSpot будет читать каталог. Достаточно прав на чтение |
| Пароль | Пароль этой учётной записи. При изменении настроек поле можно оставить пустым — тогда сохранённый пароль не меняется |
Рекомендуем ldaps:// и порт 636. Подключение по ldap:// передаёт логин, пароль и содержимое каталога по сети без шифрования. Учтите при этом, что UnSpot не проверяет сертификат сервера каталога — какие компенсирующие меры имеет смысл заложить на стороне сети, разобрано в парной статье про устройство обмена.
Шаг 2. Данные для синхронизации
В блоке «Данные для синхронизации» отметьте, какие поля переносить в карточку сотрудника. Три поля обязательные, снять их нельзя — рядом с ними подсказка «Обязательное поле для синхронизации».
| Отметка в форме | Обязательность | Что переносится |
|---|---|---|
| обязательно | Логин сотрудника в UnSpot. Из какого атрибута брать — см. шаг 3 | |
| Имя | обязательно | Атрибут givenName |
| Фамилия | обязательно | Атрибут sn |
| Отдел | по желанию | Атрибут department. Взаимоисключается с синхронизацией орг. структуры — см. шаг 4 |
| Телефон | по желанию | Атрибут telephoneNumber |
| Должность | по желанию | Атрибут title. Значение длиннее 128 символов обрезается |
| Руководитель | по желанию | Атрибут manager. В UnSpot связь строится по адресу почты руководителя, поэтому его карточка тоже должна попадать в выборку |
| Аватар пользователя | по желанию | Атрибут thumbnailPhoto. Фотографии обновляются отдельным заданием платформы, а не в общем цикле — сразу после включения отметки они не появятся |
| NumberPass | по желанию | Номер пропуска в системе контроля доступа (СКУД) — нужен для интеграций со СКУД и модуля «Посетители». Читается из атрибута numberPass; это не стандартный атрибут схемы каталога, его нужно завести самостоятельно |
Шаг 3. Основной атрибут и фильтр пользователей
В поле «Выберите основной атрибут» укажите, какой атрибут каталога считать адресом электронной почты сотрудника: userPrincipalName или Email(mail). По этому значению UnSpot сопоставляет записи каталога с карточками сотрудников, поэтому у синхронизируемых пользователей он должен быть заполнен. Записи без userPrincipalName в выборку не попадают независимо от выбора.
Поле «Фильтр для пользователей» ограничивает выборку стандартным LDAP-фильтром, длиной до 255 символов. Фильтр указывается со своими скобками — он подставляется внутрь общего условия как есть. Чтобы синхронизировать только участников конкретной группы:
(memberOf=CN=UnSpotUsers,OU=Groups,DC=mycompany,DC=ru)
Если фильтр пустой, синхронизируются все подходящие объекты внутри указанного DN. Проверьте на контроллере домена ограничение на число записей в ответе (в Active Directory — параметр MaxPageSize, по умолчанию 1000): UnSpot читает выборку одним запросом, и если каталог отдаст её не полностью, недостающие сотрудники будут выглядеть как удалённые из каталога и попадут в архив вместе с отменой своих броней. Держите фильтр таким, чтобы выборка укладывалась в лимит.
Шаг 4. Группы и организационная структура
Ниже в форме — два независимых блока, каждый со своей отметкой и своим фильтром.
| Блок | Отметка | Фильтр | Что делает |
|---|---|---|---|
| Группы | Синхронизация групп | Фильтр для групп | Группы каталога переносятся в группы UnSpot — их можно использовать в политиках бронирования, доступе к ячейкам хранения и правах доступа. Состав группы задаёт каталог: сотрудники, добавленные в такую группу вручную, будут из неё удалены при следующем цикле |
| Организационная структура | Синхронизация орг. структуры | Фильтр для организационной структуры | Из каталога переносится дерево подразделений. Для Active Directory дополнительно переносится руководитель подразделения из атрибута managedBy |
«Отдел» и «Синхронизация орг. структуры» взаимоисключаются. Включить оба нельзя: подразделение сотрудника заполняется только из одного источника. Форма блокирует второй вариант, а при попытке сохранить оба UnSpot вернёт ошибку «Нельзя одновременно синхронизировать отдел и организационную структуру».
Дерево подразделений обновляется не в каждом цикле. Оно читается в момент подключения интеграции и в момент включения отметки «Синхронизация орг. структуры». Суточный цикл и кнопка «Обновить on-premise AD» его не затрагивают, поэтому после реорганизации в каталоге снимите и снова поставьте эту отметку.
Шаг 5. Приветственные письма
Тумблер «Отправлять приветственные письма» управляет онбордингом: при создании пользователя ему будет отправлено письмо с краткой инструкцией по входу в UnSpot. В форме тумблер выключен по умолчанию. Если вы хотите сначала настроить пространство и только потом приглашать сотрудников — оставьте его выключенным. Нажмите «Сохранить»: UnSpot проверит подключение к каталогу и запустит первый обмен.
Что доступно после подключения
Карточка показывает адрес подключения и список «Поля синхронизации:». Дальше синхронизация идёт автоматически — раз в сутки по расписанию платформы. Кнопки на карточке:
| Кнопка | Когда доступна | Что делает |
|---|---|---|
| Обновить on-premise AD (в карточке OpenLDAP — «Обновить on-premise») | когда подключение исправно, не чаще одного раза в час | Запускает обмен вручную: пользователи, группы и состав групп. Фотографии и дерево подразделений не обновляет. После нажатия кнопка блокируется, а подсказка показывает время следующего запуска — «будет доступно в ЧЧ:ММ» |
| Изменить | когда подключение исправно | Открывает форму настроек: параметры подключения, набор полей, фильтры, отметки групп и оргструктуры. Это же способ сменить пароль сервисной учётной записи — переподключение для этого не нужно |
| Переподключить | только когда подключение помечено недействительным — на карточке появляется сообщение «Эта учетная запись недействительна. Пожалуйста, переподключите свой аккаунт или используйте другой» | Отключает интеграцию и подключает заново. Стирает настройки и связи между записями каталога и карточками UnSpot, после чего объекты сопоставляются заново по адресам почты. Если нужно только поменять пароль — используйте «Изменить» |
| Отключить | всегда | Останавливает синхронизацию. Карточки сотрудников и созданные группы в UnSpot сохраняются, но связи с записями каталога и признак синхронизации у подразделений удаляются |
Чем отличается карточка OpenLDAP
Рядом с AD LDAP есть отдельная карточка OpenLDAP — для каталогов OpenLDAP и совместимых. Форма настроек та же самая, кнопка ручного запуска называется «Обновить on-premise» и так же ограничена одним запуском в час. Различия, которые видны администратору:
| Что | AD LDAP | OpenLDAP |
|---|---|---|
| Класс объектов пользователей | objectClass=user | objectClass=inetOrgPerson |
| Класс объектов групп | objectClass=group | objectClass=posixGroup — требуются gidNumber и cn |
| Первый вариант «основного атрибута» | подписан userPrincipalName, читается он же | подписан userName, фактически читается uid |
| Какие атрибуты обязательны у записи | userPrincipalName | uidNumber и mail — запись без любого из них пропускается |
| Атрибут отдела | department | departmentNumber |
| Атрибут фотографии | thumbnailPhoto | jpegPhoto |
| Отключённые учётные записи | отсеиваются автоматически | не отсеиваются — исключайте их фильтром |
| Руководитель подразделения | переносится | не переносится |
Одновременно может быть подключён только один каталог — AD LDAP или OpenLDAP, и то же ограничение действует для Entra ID и Google Workspace.
Если что-то не работает
| Что видите | В чём причина | Что делать |
|---|---|---|
| «Не удалось подключиться к серверу. Проверьте указанный хост или порт» | UnSpot не дошёл до каталога | Проверьте адрес и порт, а также что межсетевой экран пропускает входящие подключения с адресов UnSpot. Частая причина — порт 389, оставленный по умолчанию при схеме ldaps:// |
| «Некорректные учетные данные для подключения» | Каталог отклонил логин или пароль | Проверьте сервисную учётную запись и что она не заблокирована и её пароль не истёк |
| «Пожалуйста, введите хост, начинающийся с ldap:// или ldaps://» | В поле «Хост» нет префикса протокола | Добавьте ldap:// или ldaps:// |
| «Синхронизация пользователей уже подключена (используется другая служба каталогов)» | Уже подключён другой способ синхронизации | Отключите текущий способ, затем подключайте этот |
| «Время синхронизации еще не наступило» | Ручной запуск был меньше часа назад | Дождитесь времени, показанного в подсказке к кнопке |
| «Нельзя одновременно синхронизировать отдел и организационную структуру» | Выбраны обе взаимоисключающие настройки | Оставьте одну — см. шаг 4 |
| Сотрудники синхронизировались не все | Выборка не прошла целиком: не заполнен основной атрибут, запись отсечена фильтром или сработало серверное ограничение на число записей | Проверьте фильтр и MaxPageSize на контроллере домена. Отсутствующие сотрудники не просто пропускаются, а архивируются — с отменой их броней |
| Дерево подразделений устарело | Оргструктура не входит в суточный цикл | Снимите и снова поставьте отметку «Синхронизация орг. структуры» |
| Аватары не появились | Фотографии обновляются отдельным заданием платформы | Дождитесь следующего запуска задания |
Историю изменений, сделанных синхронизацией, видно в разделе Аналитика → Отчёты, отчёт «История управления пользователями»: у таких записей в поле инициатора стоит признак синхронизации.
