Настройка синхронизации из on-premise AD (LDAP-SCIM)
Сервис синхронизации LDAP-SCIM переносит сотрудников и группы доступа из локальной Active Directory в UnSpot: приложение UnSpotAdScim устанавливается на машину с Windows в вашем контуре, по расписанию читает каталог по протоколу LDAP и передаёт данные в облако по стандарту SCIM. В статье — что подготовить, как создать подключение SCIM 2.0 на стороне UnSpot, как установить приложение, чем заполнить параметры подключения к каталогу и как запускать и останавливать службу. Как устроен обмен и какие данные уходят в облако, описано в статье «Синхронизация из on-premise AD (LDAP-SCIM): как устроена».
Что понадобится
Схема ниже показывает общую картину: служба синхронизации работает в вашем контуре, читает Active Directory и передаёт данные в облако UnSpot по HTTPS. Левая ветвь схемы, «СКУД API», относится к другой интеграции и в этой статье не рассматривается.
| Что | Подробности |
|---|---|
| Машина с Windows | Компьютер или сервер с 64-разрядной Windows. Синхронизация идёт, пока запущена служба, поэтому машина должна работать постоянно или включаться регулярно |
| Среда выполнения .NET 9 (x64) | Дистрибутив поставляется как MSI-инсталлятор. Запускайте установку через setup.exe — он проверит среду выполнения и при необходимости установит её |
| Права локального администратора | Нужны для установки приложения, регистрации службы Windows и управления ею |
| Учётная запись для чтения каталога | Отдельная учётная запись с правом чтения нужной ветки Active Directory. Права на запись не нужны: служба только читает |
| Сетевой доступ | С этой машины: LDAP на порт 389 или LDAPS на порт 636 до контроллера домена и исходящий HTTPS на порт 443 до вашего домена в UnSpot. Входящие правила не нужны |
| Роль в UnSpot | Подключение SCIM 2.0 создаёт «Владелец» или «Администратор интеграций» |
| Дистрибутив | Установочный файл приложения UnSpotAdScim предоставляет ваш менеджер UnSpot |
Подключение SCIM 2.0 в UnSpot
- Перейдите в «Настройки» → «Интеграции» → «Синхронизации».
- В разделе «Синхронизация пользователей» выберите карточку «SCIM 2.0» и нажмите «Подключить».
- Сохраните у себя данные URL и секретный токен: в дальнейшем токен получить будет невозможно.
- При подключении задайте «Срок работы токена» — «Без ограничения» или от 1 до 24 месяцев (срок можно изменить позже в карточке «SCIM 2.0»). Просроченный токен сервер отклоняет с ошибкой 400 «Token is expired» (неверный токен — 401 «Access denied»), а в день истечения UnSpot отправляет письмо получателям подписки «Ошибки синхронизации». Сервис синхронизации срок жизни токена не отслеживает — продлевайте его заранее.
- Настройте желаемую опцию отправки приветственных писем для сотрудников.
Установка сервиса UnSpotAdScim
- Обратитесь к своему менеджеру с просьбой предоставить установочный файл приложения UnSpotAdScim.
- Установите приложение на устройстве с ОС Windows. Дистрибутив поставляется как MSI-инсталлятор: запускайте установку через
setup.exeот имени администратора — при необходимости он установит среду выполнения .NET 9 (x64). Каталог установки по умолчанию —C:\Program Files\Umbrella IT\UnSpotAdScim. - Убедитесь, что с этой машины разрешён исходящий трафик к серверам UnSpot и доступен контроллер домена. Без этого синхронизация информации о пользователях и группах не заработает.
- Запустите файл «UnSpot AD SCIM.exe» из каталога приложения от имени администратора. При первом запуске приложение само регистрирует службу Windows «UnSpotAdScimService» — её видно в оснастке «Службы».
Настройка сервиса
Все параметры задаются в окне приложения, на вкладке «ActiveDirectory». Окно состоит из двух блоков: «Параметры подключения» — доступ к каталогу и набор синхронизируемых полей, «Параметры сервиса синхронизации» — адрес UnSpot, токен и интервал. Изменив что-либо, обязательно нажмите «Сохранить параметры»: служба читает не окно, а файл настроек.
Параметры подключения к AD
Одно подключение — один каталог. Кнопка «Добавить подключение» создаёт ещё один блок полей: подключений может быть сколько угодно, у каждого свои учётные данные, фильтры и набор полей. Лишний блок убирается кнопкой «Удалить».
| Поле | Что указать |
|---|---|
| Хост | Сетевой адрес вашего сервера, на котором установлен и работает ваш AD. Обычно это IP-адрес или доменное имя сервера |
| DN (Distinguished Name) | Уникальный идентификатор в LDAP, обозначающий запись в иерархической структуре каталогов. Он представляет полный путь к объекту от корня и состоит из пар «атрибут-значение», разделённых запятыми, и задаёт ветку, внутри которой служба ищет записи. Пример: CN=Users,DC=домен,DC=зона |
| Порт | По умолчанию для LDAP — 389, для LDAPS — 636. Флажок «шифрование» рядом с полем выставляется автоматически: для 389 снят, для 636 установлен и в обоих случаях недоступен для изменения. Менять его вручную можно только при нестандартном порте |
| Логин, пароль | Учётные данные для подключения к on-premise AD. Достаточно прав на чтение — записывать в каталог служба ничего не будет |
| Данные для синхронизации | Набор полей, которые уйдут в UnSpot. «Email», «Имя» и «Фамилия» отмечены всегда и не отключаются. Дополнительно можно включить: • «Отдел»; • «Руководитель»; • «Должность»; • «Телефон»; • «Номер пропуска»; • «Аватар» — синхронизируется из атрибута thumbnailPhoto (jpeg/png, до 100 КБ);• «Оргструктура»; • «Группы» — вместе с составом групп. «Отдел» и «Оргструктура» взаимно исключают друг друга: включение одного снимает другое |
| Фильтр для пользователей | Фильтр LDAP, ограничивающий выборку сотрудников. Если поле пустое, применяется (objectClass=user). Поиск идёт по всей ветке ниже указанного DN |
| Фильтр для групп | Фильтр LDAP для групп доступа; по умолчанию (objectClass=group). Применяется, только если отмечены «Группы» |
| Фильтр для оргструктуры | Фильтр LDAP для подразделений; по умолчанию (objectCategory=organizationalUnit). Применяется, только если отмечена «Оргструктура» |
| Поле в AD для Email | Атрибут, в котором у пользователей хранится почта: mail или userPrincipalName. Сотрудник, у которого этот атрибут не заполнен, в синхронизацию не попадает |
| UAC содержит флаги | Фильтр по атрибуту userAccountControl: синхронизируются только записи, у которых установлены все перечисленные флаги. Флаги указываются в десятичной системе через запятую |
| UAC НЕ содержит флаги | Обратный фильтр: запись пропускается, если у неё установлен любой из перечисленных флагов. Например, значение 2 исключает отключённые учётные записи. Подробнее см. в статье Использование флагов UserAccountControl |
| Префикс для групп | Применение префиксов предотвращает дублирование названий групп и обеспечивает корректную синхронизацию, когда активны несколько подключений с одинаковыми названиями групп. Префикс можно вводить на латинице и кириллице |
| Поле в AD для NumberPass | Название атрибута, в котором хранится номер пропуска. Заполняется, если отмечен «Номер пропуска»: пока поле пустое, оно подсвечивается красным, а номер пропуска в UnSpot не попадёт |
Параметры сервиса синхронизации
| Поле | Что указать |
|---|---|
| UnSpot SCIM Server | Адрес URL, сохранённый при подключении карточки «SCIM 2.0» |
| Токен авторизации в UnSpot по протоколу SCIM | Секретный токен из той же карточки. В окне значение скрыто звёздочками, но в файле настроек на диске хранится в открытом виде — ограничьте доступ к каталогу приложения |
| Задержка между синхронизациями (в часах) | Пауза между циклами: от 1 до 1000 часов, по умолчанию 24. Отсчитывается от момента завершения предыдущего цикла |
| запуск при старте Windows | Включает отложенный автозапуск службы после загрузки системы. Без этого флажка после каждой перезагрузки службу придётся запускать вручную |
Запуск и остановка службы
- «Запустить сервис» — сохраняет параметры и запускает службу. Первый цикл синхронизации начинается сразу, следующий — через заданный интервал.
- «Остановить сервис» — останавливает службу; начатый цикл прерывается.
- Поле «Статус» показывает текущее состояние — «Служба запущена» или «Служба остановлена» — и обновляется само, без перезапуска окна.
- Пока служба запущена, кнопки «Сохранить параметры» и «Запустить сервис» недоступны. Чтобы изменить настройки, остановите службу, внесите правки, сохраните их и запустите службу снова.
Служба зарегистрирована в Windows под именем «UnSpotAdScimService», поэтому запускать и останавливать её можно и из оснастки «Службы». Учтите: главный идентификатор сотрудника — адрес электронной почты. Если у пользователя в Active Directory он не заполнен, такой пользователь в UnSpot не попадёт.
Проверка и диагностика
Ход работы виден в журнале службы — файл logs\service-log.txt в каталоге приложения. В нём записан каждый цикл: сколько групп и пользователей загружено из каталога, сколько получено из UnSpot, кто создан, обновлён и удалён, а также причины, по которым запись пропущена.
| Запись в журнале | Что означает |
|---|---|
| Синхронизация групп отключена | В наборе полей не отмечены «Группы» — ни группы, ни их состав не синхронизируются |
| Поле FirstName или LastName пустое | У пользователя не заполнены givenName или sn. Имя и фамилия берутся из displayName, а если пуст и он — запись пропускается |
| Email пользователя … не валидный | Значение выбранного почтового атрибута не похоже на адрес — служба подставляет userPrincipalName |
| Пользователь пропущен по фильтрации флагов в поле UAC | Запись отсеяна настройками «UAC содержит флаги» или «UAC НЕ содержит флаги» |
| Дубль пользователя AD, Дубль группы | Одна и та же запись пришла из двух подключений или совпала по почте либо названию. В UnSpot она заведена один раз |
| Ошибка при синхронизации … | Шаг цикла завершился ошибкой. Остальные шаги при этом выполняются, повтор произойдёт в следующем цикле |
По умолчанию пишутся события уровня Info, файл ротируется раз в сутки, хранятся семь архивных копий. Для разбора проблемы можно включить подробный уровень: в файле NLog.config в каталоге приложения замените minlevel="Info" на minlevel="Debug" в правиле логирования для Release и перезапустите службу. В подробном режиме в журнал попадают тела запросов к UnSpot, то есть значения всех передаваемых полей, — верните прежний уровень сразу после диагностики.
Изменение настроек и удаление
Чтобы изменить параметры, остановите службу кнопкой «Остановить сервис», отредактируйте поля, нажмите «Сохранить параметры» и запустите службу снова. Служба перечитывает файл настроек в начале каждого цикла.
Приложение удаляется стандартно — через «Параметры» → «Приложения». При удалении служба останавливается и снимается с регистрации, файл настроек и папка журналов стираются. Файлы кэша cache.db и events.db остаются в каталоге приложения: если машина выводится из эксплуатации, удалите каталог целиком. Что лежит в этих файлах, описано в статье «Синхронизация из on-premise AD (LDAP-SCIM): как устроена».
Связанные статьи
- Синхронизация из on-premise AD (LDAP-SCIM): как устроена — вторая половина этой статьи: архитектура, состав передаваемых данных, хранение секретов и кэша.
- Синхронизация пользователей из внешней базы данных по ODBC (UnSpot ODBC SCIM Adapter) — родственный мост: сотрудники берутся не из AD, а из любой СУБД через ODBC.
- Обзор интеграций.
