Настройка синхронизации с Active Directory (AD LDAP / OpenLDAP)
Инструкция для администратора UnSpot и администратора каталога: как подключить синхронизацию сотрудников из локального Active Directory или OpenLDAP, какие поля перенести и как ограничить выборку. Подключение выполняется в разделе Настройка → Интеграции, в блоке «Синхронизация пользователей». Настраивать интеграции могут роли Владелец и Администратор интеграций. Как устроен сам обмен и что уходит из каталога — в парной статье «Синхронизация пользователей с Active Directory (AD LDAP / OpenLDAP): как устроена»; её же передают службе информационной безопасности на согласование.
Что понадобится
- Роль в UnSpot: Владелец или Администратор интеграций.
- Сетевой доступ: контроллер домена должен принимать входящие подключения с адресов UnSpot (актуальный список адресов запросите в поддержке) на порт 389 или 636 — смотря какой протокол вы выберете. Без сетевого доступа форма не сохранится: настройки записываются только после успешно пройденной проверки интеграции (шаг 7).
- Сервисная учётная запись в каталоге с правами только на чтение объектов пользователей, групп и подразделений.
- DN контейнера, от которого искать сотрудников.
- Свободный слот синхронизации: одновременно может быть подключён только один способ — AD LDAP, OpenLDAP, Entra ID или Google Workspace. Если подключён другой, сначала отключите его.
Шаг 1. Подключение протокола
Откройте Настройка → Интеграции. В блоке «Синхронизация пользователей» собраны все способы: у AD LDAP, OpenLDAP, Entra ID (Azure AD), Google Workspace и SCIM 2.0 есть кнопка «Подключить», а CSV и OpenID Connect ведут ссылкой «Перейти к настройке» в свои разделы.
Нажмите «Подключить» в карточке AD LDAP — откроется форма «Настройки синхронизации» (у уже настроенной интеграции та же форма открывается кнопкой «Изменить»). Форма заполняется сверху вниз и разделена на четыре блока — именно в этом порядке:
- Подключение протокола — протокол, адрес сервера каталога, порт, DN и учётные данные сервисной записи.
- Параметры синхронизации для пользователей.
- Маппинг данных о пользователе — из каких атрибутов каталога брать поля карточки сотрудника.
- Параметры синхронизации для пользователей — фильтр по пользователям, и Дополнительные параметры синхронизации — группы доступа, оргструктура и приветственные письма; у групп и оргструктуры свои фильтры.
Под блоками — «Проверка интеграции»: пока она не пройдена, подключение не сохраняется (шаг 7). Начните с блока «Подключение протокола»:
| Поле | Что указать |
|---|---|
| Протокол | Обязательный список: «LDAP · без шифрования (389)» или «LDAPS · с шифрованием (636)». Пока значение не выбрано, в поле стоит подсказка «Выберите протокол» |
| Хост | Сетевой адрес сервера каталога без префикса протокола — например dc01.mycompany.ru. Префикс в это поле больше не пишут: UnSpot подставляет его по выбранному протоколу при сохранении, а у уже настроенного подключения определяет протокол по сохранённому адресу |
| DN* | Отличительное имя контейнера, от которого искать пользователей. Под полем показан образец: «Пример CN=Users, DC=mycompany, DC=ru». Поле обязательное: искать от корня каталога нельзя |
| Порт | Подставляется сам при выборе протокола — 389 для LDAP и 636 для LDAPS, — если поле пустое или в нём стоит порт по умолчанию другого протокола. Нестандартный порт укажите вручную: введённое значение подстановка не затирает |
| Логин | Учётная запись, под которой UnSpot будет читать каталог. Достаточно прав на чтение. Строка передаётся в bind как есть — подойдёт UPN (svc-unspot@corp.local) или полный DN |
| Пароль | Пароль этой учётной записи. При новом подключении поле обязательное. При изменении существующего подключения его можно оставить пустым — тогда сохранённый пароль не меняется |
Выбирайте «LDAPS · с шифрованием (636)», если каталог принимает такие подключения. Вариант «LDAP · без шифрования (389)» передаёт логин, пароль и содержимое каталога по сети без шифрования. Какие компенсирующие меры имеет смысл заложить на стороне сети, разобрано в парной статье про устройство обмена.
Шаг 2. Маппинг данных о пользователе
Блок «Маппинг данных о пользователе» отвечает на вопрос, из каких атрибутов каталога брать поля карточки сотрудника. Три поля — Email, имя и фамилия — задаются списками: пока значение не выбрано, в поле стоит подсказка «Выберите атрибут». Все три обязательны, и значения по умолчанию у них нет: раньше в поле Email подставлялся первый вариант, теперь его выбирают руками. Остальные поля остались отметками, но рядом с каждой подписано имя атрибута: department, manager, position, telephoneNumber, thumbnailPhoto. Подписи фиксированные и не всегда совпадают с тем, что UnSpot действительно читает: должность берётся из атрибута title, а в карточке OpenLDAP отдел читается из departmentNumber, а фотография — из jpegPhoto. Отмечать эти поля необязательно — подключиться можно, заполнив только три обязательных списка.
| Поле в форме | Варианты в списке | Что это значит |
|---|---|---|
| Email* | userPrincipalName (в карточке AD LDAP) или userName (в карточке OpenLDAP); Email | Логин сотрудника в UnSpot. По этому значению записи каталога сопоставляются с карточками сотрудников, поэтому у синхронизируемых пользователей атрибут должен быть заполнен. Записи без userPrincipalName в выборку не попадают независимо от выбора |
| Имя* | givenName; «displayName (фамилия ИМЯ отчество)»; «displayName (ИМЯ отчество фамилия)» | Имя в карточке сотрудника. Первый вариант берёт атрибут целиком, два других вырезают нужное слово из displayName |
| Фамилия* | sn; «displayName (ФАМИЛИЯ имя отчество)»; «displayName (имя отчество ФАМИЛИЯ)» | Фамилия в карточке сотрудника. Первый вариант берёт атрибут целиком, два других вырезают нужное слово из displayName |
Как разбирается displayName. Значение режется по пробелам, кратные пробелы схлопываются. Первая часть — первое слово строки, средняя — второе, последняя — последнее. Заглавные буквы в подписи варианта показывают, какое слово попадёт в поле: «displayName (фамилия ИМЯ отчество)» возьмёт в имя второе слово, «displayName (имя отчество ФАМИЛИЯ)» возьмёт в фамилию последнее. Если нужного слова в строке нет — например, в displayName всего одно слово — или атрибут пуст, UnSpot берёт значение из givenName для имени и из sn для фамилии.
Если пусты и givenName со sn, срабатывает последний фоллбэк: в карточке AD LDAP имя и фамилия достаются из атрибута name (строка делится по первому пробелу), в карточке OpenLDAP на их место подставляется адрес электронной почты. И только если после всех фоллбэков имя или фамилия остались пустыми, сотрудник молча пропускается при синхронизации — ни ошибки в интерфейсе, ни записи в журнале, ни строки в сводке при этом не будет, карточка просто не появится. На практике до этого доходит редко. Гораздо чаще неверно выбранный источник виден иначе: имя или фамилия в карточке выглядят как название записи каталога или как адрес почты. Тогда проверьте, что выбранный вариант разбора displayName подходит формату, принятому в вашем каталоге.
| Отметка в форме | Атрибут рядом с отметкой | Что переносится |
|---|---|---|
| Отображаемое имя | displayName | Поле «Отображаемое имя» в карточке сотрудника — имя, под которым сотрудник виден по всему продукту. Отметка появилась 31.08.2026 и по умолчанию выключена. Атрибут переносится как есть, без разбора на слова и без фоллбэков: если displayName в каталоге пуст или его нет, поле в карточке будет затёрто. Пока отметка снята, поле не трогается — остаётся то, что заполнили руками. Включённая отметка делает поле в карточке сотрудника нередактируемым: при наведении показывается подсказка «Вы не можете редактировать это поле, так как этот пользователь синхронизируется с Active Directory» |
| Отдел | department | Отдел в карточке сотрудника. Взаимоисключается с синхронизацией оргструктуры — см. шаг 5 |
| Руководитель | manager | Руководитель в карточке. В UnSpot связь строится по адресу почты руководителя, поэтому его карточка тоже должна попадать в выборку |
| Должность | position | Должность в карточке. Значение длиннее 128 символов обрезается |
| Телефон | telephoneNumber | Телефон в карточке сотрудника |
| Аватар | thumbnailPhoto | Фотография сотрудника. Переносится отдельным заданием: оно запускается сразу при подключении интеграции и при включении отметки, а последующие смены фото в каталоге подхватываются по расписанию платформы; суточный цикл и кнопка ручного запуска фотографии не обновляют |
Шаг 3. Номер пропуска СКУД
Строка «Номер пропуска СКУД» (раньше подпись выглядела как NumberPass) устроена иначе остальных: она устроена иначе остальных: рядом с отметкой стоит не имя атрибута, а текстовое поле с подсказкой «Укажите LDAP-атрибут». Номер пропуска нужен интеграциям со СКУД и модулю «Посетители».
- Пока отметка снята, поле недоступно и остаётся пустым, а атрибут из каталога не вычитывается.
- Когда отметку ставят, поле становится обязательным.
- Значение — любое имя атрибута вашего каталога: закрытого списка нет. Номер пропуска редко лежит в стандартном атрибуте схемы, поэтому его обычно заводят сами; значение по умолчанию —
numberPass.
Шаг 4. Дополнительные параметры синхронизации
Начните с блока «Параметры синхронизации для пользователей»: в нём одно поле — «Фильтр по пользователям», и оно решает, кто вообще попадёт в синхронизацию.
Поле «Фильтр по пользователям» ограничивает выборку стандартным LDAP-фильтром, длиной до 255 символов. Фильтр указывается со своими скобками — он подставляется внутрь общего условия как есть. Чтобы синхронизировать только участников конкретной группы:
(memberOf=CN=UnSpotUsers,OU=Groups,DC=mycompany,DC=ru)
Если фильтр пустой, синхронизируются все подходящие объекты внутри указанного DN. Проверьте на контроллере домена ограничение на число записей в ответе (в Active Directory — параметр MaxPageSize, по умолчанию 1000): UnSpot читает выборку одним запросом, и если каталог отдаст её не полностью, недостающие сотрудники будут выглядеть как удалённые из каталога и попадут в архив вместе с отменой своих броней. Держите фильтр таким, чтобы выборка укладывалась в лимит.
Шаг 5. Группы и организационная структура
В том же блоке — два независимых переключателя, у каждого своё описание и свой фильтр. Поля фильтров видны всегда, но остаются неактивными, пока переключатель выключен. Фильтр по группам и фильтр для орг. структуры принимают до 255 знаков.
| Переключатель | Фильтр | Что делает |
|---|---|---|
| Синхронизировать группы доступа | Фильтр по группам | В форме описан словами «Загружать группы доступа из AD». Группы каталога переносятся в группы UnSpot — их можно использовать в политиках бронирования, доступе к ячейкам хранения и правах доступа. Состав группы задаёт каталог: синхронизируемые сотрудники, добавленные в такую группу вручную, будут из неё удалены при следующем цикле; карточек, заведённых в UnSpot вручную и не связанных с каталогом, это не касается. Группа, пропавшая из каталога или не прошедшая фильтр, удаляется из UnSpot целиком — вместе с её ролью в политиках бронирования и правах |
| Синхронизировать оргструктуру | Фильтр для орг. структуры | В форме описан словами «Построить дерево подразделений из AD». Из каталога переносится дерево подразделений. Для Active Directory дополнительно переносится руководитель подразделения из атрибута managedBy |
«Отдел» и «Синхронизировать оргструктуру» взаимоисключаются. Включить оба нельзя: подразделение сотрудника заполняется только из одного источника. Форма блокирует второй вариант, а при попытке сохранить оба UnSpot вернёт ошибку «Нельзя одновременно синхронизировать отдел и организационную структуру».
Дерево подразделений обновляется не в каждом цикле. Оно читается в момент подключения интеграции и в момент включения переключателя «Синхронизировать оргструктуру». Суточный цикл и кнопка «Обновить on-premise AD» его не затрагивают, поэтому после реорганизации в каталоге выключите и снова включите этот переключатель.
Шаг 6. Приветственные письма
Тумблер «Отправлять приветственные письма» управляет онбордингом: в форме он описан словами «При создании пользователя ему придёт письмо с краткой инструкцией». По умолчанию тумблер выключен. Если вы хотите сначала настроить пространство и только потом приглашать сотрудников — оставьте его выключенным.
Шаг 7. Проверка интеграции
Внизу формы — блок «Проверка интеграции» с кнопкой «Проверить интеграцию». Проверка обращается к каталогу с теми параметрами, что заполнены в форме, и возвращает до пяти строк:
| Что проверяется | Строка при успехе | Строка при ошибке | Что она значит |
|---|---|---|---|
| Соединение | Хост доступен, соединение установлено | Ошибка подключения. Проверьте протокол подключения, адрес сервера, порт. | UnSpot дошёл до сервера каталога по выбранному протоколу, адресу и порту |
| Учётные данные | Учётные данные приняты | Не удалось пройти авторизацию. Проверьте логин и пароль учетной записи. | Каталог принял логин и пароль сервисной записи. Строка появляется только если соединение установилось |
| Пользователи | Пользователи найдены | Пользователи: Не найдены | В указанном DN с учётом фильтра по пользователям нашлась хотя бы одна запись пользователя |
| Группы доступа | Группы доступа найдены | Группы доступа: Не найдены | Нашлась хотя бы одна группа, проходящая фильтр по группам. Строка показывается только при включённом переключателе групп |
| Подразделения | Подразделения найдены | Подразделения: Не найдены | Нашлось хотя бы одно подразделение, проходящее фильтр для орг. структуры. Строка показывается только при включённой синхронизации оргструктуры |
Строки про пользователей, группы и подразделения появляются только тогда, когда прошли и соединение, и авторизация: пока UnSpot не дошёл до каталога, проверять выборку нечем.
Без успешно пройденной проверки подключение не сохраняется. Кнопка сохранения запускает проверку сама, и настройки записываются только при её успехе. Успехом считаются соединение, учётные данные и пользователи, а также группы и подразделения, если соответствующие переключатели включены. Если обязательные поля формы не заполнены или сам запрос проверки не выполнился, под блоком появляется «Проверка интеграции не пройдена». Если проверка выполнилась, но какие-то строки её не прошли, отдельного сообщения не будет — смотрите сами строки в блоке. При сбое запроса дополнительно всплывает сообщение об ошибке; когда сервер ничего не вернул, это «Не удалось выполнить проверку LDAP-интеграции».
Любое изменение параметров подключения сбрасывает результат проверки. Смена протокола, хоста, порта, DN, логина, пароля, фильтров или переключателей означает, что проверку нужно проходить заново.
Ещё две вещи, о которых стоит знать заранее. Неудачная проверка не помечает существующую интеграцию нерабочей: состояние уже настроенного подключения она не меняет, синхронизация продолжает идти на прежних параметрах. И проверка читает по одной записи каждого типа, поэтому отвечает на вопрос «доступно ли вообще», а не «сколько сотрудников загрузится»: пройденная проверка не обещает, что в выборку попадут все нужные сотрудники.
Что доступно после подключения
Карточка показывает адрес подключения и список «Поля синхронизации:» — номер пропуска в нём теперь называется «Номер пропуска», а не NumberPass. Дальше синхронизация идёт автоматически — раз в сутки по расписанию платформы. Кнопки на карточке:
| Кнопка | Когда доступна | Что делает |
|---|---|---|
| Обновить on-premise AD (в карточке OpenLDAP — «Обновить on-premise») | когда подключение исправно, не чаще одного раза в час | Запускает обмен вручную: пользователи, группы и состав групп. Фотографии и дерево подразделений не обновляет. После нажатия кнопка блокируется, а подсказка показывает время следующего запуска — «будет доступно в ЧЧ:ММ» |
| Изменить | когда подключение исправно | Открывает форму настроек: параметры подключения, набор полей, фильтры, отметки групп и оргструктуры. Добавленные отметки применяются сразу — UnSpot запускает внеплановый обмен, не дожидаясь суточного цикла; снятие отметки вступает в силу со следующего цикла. Это же способ сменить пароль сервисной учётной записи — переподключение для этого не нужно. Пароль при изменении можно не вводить, но сохранить форму всё равно удастся только после успешной проверки интеграции |
| Переподключить | только когда подключение помечено недействительным — на карточке появляется сообщение «Эта учетная запись недействительна. Пожалуйста, переподключите свой аккаунт или используйте другой» | Отключает интеграцию: стирает настройки и связи между записями каталога и карточками UnSpot. Подключение придётся собрать заново кнопкой «Подключить» — форма откроется пустой, а объекты сопоставятся заново по адресам почты. Если нужно только поменять пароль — используйте «Изменить» |
| Отключить | всегда | Останавливает синхронизацию. Карточки сотрудников и созданные группы в UnSpot сохраняются, но связи с записями каталога и признак синхронизации у подразделений удаляются (если параллельно подключён SCIM-провижининг, признак у подразделений сохраняется) |
Чем отличается карточка OpenLDAP
Рядом с AD LDAP есть отдельная карточка OpenLDAP — для каталогов OpenLDAP и совместимых. Форма настроек та же самая, кнопка ручного запуска называется «Обновить on-premise» и так же ограничена одним запуском в час. Различия, которые видны администратору:
| Что | AD LDAP | OpenLDAP |
|---|---|---|
| Класс объектов пользователей | objectClass=user | objectClass=inetOrgPerson |
| Класс объектов групп | objectCategory=group | objectClass=posixGroup — требуются gidNumber и cn |
| Первый вариант в списке для поля Email* | подписан userPrincipalName, читается он же | подписан userName, фактически читается uid |
| Какие атрибуты обязательны у записи | userPrincipalName | uidNumber и mail — запись без любого из них пропускается |
| Атрибут отдела | department | departmentNumber |
| Атрибут фотографии | thumbnailPhoto | jpegPhoto |
| Отключённые учётные записи | отсеиваются автоматически | не отсеиваются — исключайте их фильтром |
| Руководитель подразделения | переносится | не переносится |
Одновременно может быть подключён только один каталог — AD LDAP или OpenLDAP, и то же ограничение действует для Entra ID и Google Workspace.
Готовые шаблоны для «Фильтра по пользователям» OpenLDAP. Выбор членов двух групп (нужен включённый оверлей memberOf): (|(memberOf=cn=unspot-users,ou=groups,dc=example,dc=com)(memberOf=cn=contractors,ou=groups,dc=example,dc=com)). Исключение заблокированных — по атрибуту вашей схемы, например (!(nsAccountLock=TRUE)) в 389 Directory Server и FreeIPA. Помните, что фильтр вставляется внутрь служебного запроса вместе со своими скобками.
Если что-то не работает
| Что видите | В чём причина | Что делать |
|---|---|---|
| «Ошибка подключения. Проверьте протокол подключения, адрес сервера, порт.» | Проверка интеграции не дошла до каталога | Проверьте протокол, адрес и порт, а также что межсетевой экран пропускает входящие подключения с адресов UnSpot. Частая причина — протокол и порт, которых каталог не слушает. UnSpot ждёт ответа каталога 5 секунд — при задержках на канале проверка может не пройти, даже если каталог жив |
| «Не удалось пройти авторизацию. Проверьте логин и пароль учетной записи.» | Каталог отклонил логин или пароль | Проверьте сервисную учётную запись и что она не заблокирована и её пароль не истёк |
| «Проверка интеграции не пройдена» | Форма не сохраняется, пока проверка не пройдена целиком | Нажмите «Проверить интеграцию» и разберите строки, которые не прошли. Помните, что правка любого параметра подключения сбрасывает результат проверки |
| «Не удалось выполнить проверку LDAP-интеграции» | Сам запрос проверки не выполнился | Убедитесь, что обязательные поля формы заполнены, и запустите проверку ещё раз |
| «Синхронизация пользователей уже подключена (используется другая служба каталогов)» | Уже подключён другой способ синхронизации | Отключите текущий способ, затем подключайте этот |
| «Время синхронизации еще не наступило» | Ручной запуск был меньше часа назад | Дождитесь времени, показанного в подсказке к кнопке |
| «Нельзя одновременно синхронизировать отдел и организационную структуру» | Выбраны обе взаимоисключающие настройки | Оставьте одну — см. шаг 5 |
| Сотрудники синхронизировались не все | Выборка не прошла целиком: не заполнен атрибут, выбранный для Email, запись отсечена фильтром, сработало серверное ограничение на число записей — либо после разбора displayName у сотрудника оказались пусты имя или фамилия, и он был пропущен молча | Сверьте выбранные источники имени и фамилии с тем, что лежит в каталоге, затем проверьте фильтр и MaxPageSize на контроллере домена. Пропущенные из-за пустого имени сотрудники просто не появятся, а вот те, кто исчез из выборки, архивируются — с отменой их броней |
| Дерево подразделений устарело | Оргструктура не входит в суточный цикл | Выключите и снова включите переключатель «Синхронизировать оргструктуру» |
| Аватары не появились | Фото переносит отдельное задание: внеплановый запуск — сразу при подключении и при включении отметки, дальше — по расписанию платформы | Если фото нет и сразу после включения отметки — проверьте права учётной записи на чтение thumbnailPhoto; смена фото в каталоге появится после следующего запуска задания |
Историю изменений, сделанных синхронизацией, видно в разделе Аналитика → Отчёты, отчёт «История управления пользователями»: у таких записей в поле инициатора стоит признак синхронизации.
Связанные статьи
- Синхронизация пользователей с Active Directory (AD LDAP / OpenLDAP): как устроена
- Настройка синхронизации из on-premise AD (LDAP-SCIM)
- Настройка синхронизации по ODBC (UnSpot ODBC SCIM Adapter)
- Синхронизация по SCIM 2.0 (Entra ID, Okta): как устроена
- Обзор интеграций
- Как выбрать способ синхронизации пользователей
