Настройка синхронизации из on-premise AD (LDAP-SCIM)

Сервис синхронизации LDAP-SCIM переносит сотрудников, группы доступа и оргструктуру из локальной Active Directory в UnSpot: приложение UnSpotAdScim устанавливается на машину с Windows в вашем контуре, по расписанию читает каталог по протоколу LDAP и передаёт данные в облако по стандарту SCIM. В статье — что подготовить, как создать подключение SCIM 2.0 на стороне UnSpot, как установить приложение, чем заполнить параметры подключения к каталогу и как запускать и останавливать службу. Отдельный раздел — про вторую службу того же агента, которая передаёт в UnSpot события прохода из СКУД RusGuard. Как устроен обмен и какие данные уходят в облако, описано в статье «Синхронизация из on-premise AD (LDAP-SCIM): как устроена».

Что понадобится

Схема ниже показывает общую картину: служба синхронизации работает в вашем контуре, читает Active Directory и передаёт данные в облако UnSpot по HTTPS. Левая ветвь схемы, «СКУД API», относится к другой интеграции и в этой статье не рассматривается.

Что	Подробности
Машина с Windows	Компьютер или сервер с 64-разрядной Windows. Синхронизация идёт, пока запущена служба, поэтому машина должна работать постоянно или включаться регулярно
Среда выполнения .NET 10 (x64)	Дистрибутив поставляется как MSI-инсталлятор. Запускайте установку через setup.exe — он проверит среду выполнения и при необходимости установит «Среда выполнения .NET 10.0.9 (x64)»
Права локального администратора	Нужны для установки приложения, регистрации службы Windows и управления ею
Учётная запись для чтения каталога	Отдельная учётная запись с правом чтения нужной ветки Active Directory. Права на запись не нужны: служба только читает
Сетевой доступ	С этой машины: LDAP на порт 389 или LDAPS на порт 636 до контроллера домена и исходящий HTTPS на порт 443 до вашего домена в UnSpot. Входящие правила не нужны
Роль в UnSpot	Подключение SCIM 2.0 создаёт «Владелец» или «Администратор интеграций»
Дистрибутив	Установочный файл приложения UnSpotAdScim предоставляет ваш менеджер UnSpot

Подключение SCIM 2.0 в UnSpot

Видео записано в предыдущей версии интерфейса агента; расположение и названия полей описаны ниже по актуальной версии.

1. Перейдите в «Настройки» → «Интеграции» → «Синхронизации».
2. В разделе «Синхронизация пользователей» выберите карточку «SCIM 2.0» и нажмите «Подключить».
3. Сохраните у себя данные URL и секретный токен: в дальнейшем токен получить будет невозможно.
4. При подключении задайте «Срок работы токена» — «Без ограничения» или от 1 до 24 месяцев (срок можно изменить позже в карточке «SCIM 2.0»). Просроченный токен сервер отклоняет с ошибкой 400 «Token is expired» (неверный токен — 401 «Access denied»), а в день истечения UnSpot отправляет письмо получателям подписки «Ошибки синхронизации». Сервис синхронизации срок жизни токена не отслеживает — продлевайте его заранее.
5. Настройте желаемую опцию отправки приветственных писем для сотрудников.

Установка сервиса UnSpotAdScim

Видео записано в предыдущей версии интерфейса агента; расположение и названия полей описаны ниже по актуальной версии.

1. Обратитесь к своему менеджеру с просьбой предоставить установочный файл приложения UnSpotAdScim.
2. Установите приложение на устройстве с ОС Windows. Дистрибутив поставляется как MSI-инсталлятор: запускайте установку через setup.exe от имени администратора — при необходимости он установит среду выполнения .NET 10 (x64). Каталог установки по умолчанию — C:\Program Files\Umbrella IT\UnSpotAdScim.
3. Убедитесь, что с этой машины разрешён исходящий трафик к серверам UnSpot и доступен контроллер домена. Без этого синхронизация информации о пользователях и группах не заработает.
4. Запустите файл «UnSpot AD SCIM.exe» из каталога приложения от имени администратора. При первом запуске приложение само регистрирует две службы Windows — «UnSpotAdScimService» (синхронизация пользователей) и «UnSpotRusGuardService» (события СКУД RusGuard); обе видны в оснастке «Службы». В шапке окна показана версия агента (актуальная — 3.0.9).

Настройка сервиса

Видео записано в предыдущей версии интерфейса агента; расположение и названия полей описаны ниже по актуальной версии.

Все параметры задаются в окне приложения «Синхронизация с UnSpot». Слева — навигация по разделам, сгруппированным по двум службам; справа — поля выбранного раздела; внизу — строка состояния службы и кнопки «Сохранить», «Запустить», «Остановить». В шапке окна показана версия агента. Служба читает не окно, а файл настроек, поэтому после любых правок нажимайте «Сохранить» (или сразу «Запустить» — она сохраняет параметры перед запуском).

Группа в навигации	Раздел	Что задаёт
Синхронизация пользователей	«Windows служба для User Sync»	интервал синхронизации, автозапуск, журнал и время последней синхронизации
Синхронизация пользователей	«Подключение к UnSpot SCIM API»	адрес и токен, сохранённые при подключении карточки «SCIM 2.0»
Синхронизация пользователей	«Подключение к Active Directory»	подключения к каталогам, маппинг атрибутов и фильтры
Синхронизация со СКУД	«Windows служба для СКУД Sync»	период опроса событий и автозапуск второй службы
Синхронизация со СКУД	«Подключение к UnSpot PACS API»	адрес и токен входящей подписки СКУД в UnSpot
Синхронизация со СКУД	«Подключение к СКУД RusGuard»	адрес, учётные данные и правила передачи событий RusGuard

Для синхронизации пользователей нужны только три раздела первой группы — их и разбираем ниже, в порядке заполнения. Вторая группа относится к передаче событий прохода из СКУД RusGuard и описана в разделе «Синхронизация со СКУД RusGuard»; если такой СКУД у вас нет, эти разделы можно не заполнять.

Подключение к UnSpot SCIM API

Поле	Что указать
Адрес сервера (UnSpot SCIM API) *	Адрес URL, сохранённый при подключении карточки «SCIM 2.0»
Токен авторизации для UnSpot SCIM API *	Секретный токен из той же карточки. В файле настроек на диске он хранится в открытом виде — ограничьте доступ к каталогу приложения

Кнопка «Проверить подключение» обращается к серверу с указанным токеном и показывает результат прямо под полями:

• «✓ Подключено / Сервер отвечает» — адрес и токен верны;
• «✗ Неверный токен авторизации» — сервер ответил кодом 401 или 403: проверьте токен и его срок действия;
• «✗ SCIM endpoint не найден / проверьте адрес сервера» — код 404: адрес указан с ошибкой;
• «✗ Нет подключения: …» — сервер недоступен с этой машины, текст после двоеточия — причина.

Подключение к Active Directory

Одно подключение — один каталог. Подключения показаны карточками: кнопка «+ Добавить подключение» создаёт новую, в заголовке карточки — хост и DN подключения. Подключений может быть сколько угодно, у каждого свои учётные данные, маппинг и фильтры. Лишняя карточка убирается кнопкой «Удалить подключение» — с подтверждением. У каждой карточки есть своя кнопка «Проверить подключение»: она выполняет поиск по указанному DN и отвечает «✓ Сервер отвечает (HTTP 200)» (с припиской «, объектов в DN не найдено», если ветка пуста) или «✗ Нет подключения: …». «HTTP 200» здесь — условное обозначение успеха, а не код ответа LDAP.

Блок «Параметры подключения»:

Поле	Что указать
Протокол *	Вариант «LDAP · без шифрования» или «LDAPS · с шифрованием». При выборе протокола порт подставляется автоматически: 389 для LDAP, 636 для LDAPS. Работает и обратное: ввод порта 636 включает шифрование
Хост *	Сетевой адрес сервера, на котором работает ваш AD. Обычно это IP-адрес или доменное имя контроллера домена
Порт	Порт LDAP. Менять вручную нужно только при нестандартном порте — стандартный подставляется по протоколу
Логин, Пароль	Учётные данные для подключения к on-premise AD. Достаточно прав на чтение — записывать в каталог служба ничего не будет
DN (Distinguished Name) – точка входа *	Уникальный идентификатор в LDAP, обозначающий запись в иерархической структуре каталогов. Он представляет полный путь к объекту от корня и состоит из пар «атрибут-значение», разделённых запятыми, и задаёт ветку, внутри которой служба ищет записи. Пример: CN=Users,DC=домен,DC=зона

Блок «Маппинг данных о пользователе» («Атрибут Active Directory → поле UnSpot») задаёт, откуда берётся каждое поле сотрудника. Три поля обязательны, для каждого нужно выбрать источник:

Поле UnSpot	Варианты атрибута AD	Примечание
Email	• mail • userPrincipalName	Главный идентификатор сотрудника. Сотрудник, у которого выбранный атрибут не заполнен, в синхронизацию не попадает
Имя	• First name (givenName) • Display name (фамилия ИМЯ отчество) • Display name (ИМЯ отчество фамилия)	Варианты «Display name» берут нужную часть атрибута displayName, разбирая его по пробелам — выбирайте по тому, в каком порядке у вас записаны ФИО
Фамилия	• Last name (sn) • Display name (ФАМИЛИЯ имя отчество) • Display name (имя отчество ФАМИЛИЯ)	То же для фамилии

Дополнительные поля включаются чекбоксами:

Чекбокс	Что уходит в UnSpot
«Отдел»	атрибут department. Взаимоисключающий с «Оргструктурой»: включение одного снимает другое
«Руководитель»	атрибут manager
«Должность»	атрибут title
«Телефон»	атрибут telephoneNumber
«Аватар»	атрибут thumbnailPhoto. Ограничение 100 КБ проверяет сервер UnSpot: фото крупнее он отклонит, а в журнале появится ошибка отправки аватара
«Номер пропуска»	атрибут, имя которого вы вводите в поле рядом с чекбоксом («поле AD»). Пока чекбокс включён, а поле пустое, сохранить параметры нельзя
«Группы»	группы доступа вместе с их составом. Включает поля «Фильтр для групп, синтаксис LDAP» и «Префикс для названия групп в UnSpot»
«Оргструктура»	подразделения по атрибуту distinguishedName. Взаимоисключающая с «Отделом»; включает поле «Фильтр для оргструктуры (LDAP)»

Ниже в той же карточке — фильтры выборки:

Поле	Что указать
Фильтр для пользователей (LDAP)	Фильтр LDAP, ограничивающий выборку сотрудников. Если поле пустое, применяется (objectClass=user). Поиск идёт по всей ветке ниже указанного DN
UAC содержит флаги	Фильтр по атрибуту userAccountControl: синхронизируются только записи, у которых установлены все перечисленные флаги. Флаги указываются в десятичной системе через запятую, например 512
UAC не содержит флаги	Обратный фильтр: запись пропускается, если у неё установлен любой из перечисленных флагов. Например, значение 2 исключает отключённые учётные записи. Подробнее см. в статье Использование флагов UserAccountControl
Синхронизировать группы доступа	Флажок блока «Синхронизация групп доступа» — то же, что чекбокс «Группы» в маппинге: состав группы берётся из атрибута member
Фильтр для групп, синтаксис LDAP	Фильтр LDAP для групп доступа; по умолчанию (objectClass=group). Применяется, только если включена синхронизация групп
Префикс для названия групп в UnSpot	Применение префиксов предотвращает дублирование названий групп и обеспечивает корректную синхронизацию, когда активны несколько подключений с одинаковыми названиями групп. Префикс можно вводить на латинице и кириллице
Синхронизировать оргструктуру	Флажок блока «Синхронизация оргструктуры» — то же, что чекбокс «Оргструктура» в маппинге; исключает синхронизацию поля «Отдел»
Фильтр для оргструктуры (LDAP)	Фильтр LDAP для подразделений; по умолчанию (objectCategory=organizationalUnit). Применяется, только если включена синхронизация оргструктуры

Windows служба для User Sync

Раздел управляет службой Windows «UnSpotAdScimService», которая и выполняет синхронизацию. В заголовке раздела показан её статус — «Запущена», «Остановлена» или «Служба не установлена»; он обновляется сам, без перезапуска окна.

Элемент	Что делает
Интервал синхронизации	Как часто выполнять полную синхронизацию: от 1 до 1000 часов, по умолчанию 24 (единица — «ч»). Подсказка под полем напоминает: служба перечитывает параметры перед каждым циклом, поэтому изменения применятся со следующего цикла; чтобы применить их немедленно, перезапустите службу
Запускать при старте Windows	Тумблер автозапуска службы после загрузки системы. Без него после каждой перезагрузки службу придётся запускать вручную
Logs	Кнопка открывает папку журналов приложения
Последняя синхронизация: …	Время начала и окончания последнего цикла; строка появляется после первой синхронизации

Синхронизация со СКУД RusGuard

Вторая группа разделов — «Синхронизация со СКУД» — настраивает отдельную службу Windows «UnSpotRusGuardService» (PACS Sync). Она опрашивает СКУД RusGuard и передаёт события прохода сотрудников в UnSpot: так UnSpot узнаёт, что сотрудник в офисе, и подтверждает его брони. Эта служба независима от синхронизации пользователей: её можно не запускать вовсе, а можно запускать без User Sync.

На стороне UnSpot для неё нужна входящая подписка СКУД в формате JSON — как её создать и какой адрес и токен она выдаёт, описано в статье Входящие вебхуки: подключение СКУД.

Раздел	Поле	Что указать
Windows служба для СКУД Sync	Период опроса событий	Как часто запрашивать у RusGuard новые события прохода: от 2 до 120 секунд, по умолчанию 5. Новое значение применяется после перезапуска службы
Windows служба для СКУД Sync	Запускать при старте Windows	Тумблер автозапуска — как у службы User Sync
Подключение к UnSpot PACS API	Адрес сервера (UnSpot PACS API) *	Полный URL входящей подписки СКУД из UnSpot — тот, что показан в карточке подписки. На этот же адрес служба отправляет события
Подключение к UnSpot PACS API	Токен авторизации для UnSpot PACS API	Токен подписки, если он в ней задан. Поле необязательное
Подключение к СКУД RusGuard	Адрес сервера (RusGuard SOAP API) *	Адрес SOAP-интерфейса сервера RusGuard
Подключение к СКУД RusGuard	Логин *, Пароль	Учётные данные RusGuard; пароль необязателен
Подключение к СКУД RusGuard	Передавать события только по пользователям, синхронизируемым из Active Directory	Флажок в блоке «Обработка событий». Если включён, события по людям, которых нет в UnSpot, не передаются. Фильтр опирается на список пользователей, полученный службой User Sync, — пока синхронизация с Active Directory ни разу не выполнялась, все события RusGuard пропускаются

В обоих разделах подключения есть кнопка «Проверить подключение». Для UnSpot PACS API результаты такие:

• «✓ Подключено / Сервер отвечает» — подписка найдена, токен принят;
• «✗ Неверный токен авторизации» — код 401: токен не совпадает с токеном подписки;
• «✗ Подписка на события СКУД отключена» — код 403: включите подписку в UnSpot;
• «✗ Подписка на события СКУД не найдена» — код 404: проверьте адрес;
• «✗ Нет подключения: …» — сервер недоступен с этой машины.

Для RusGuard проверка выполняет вход на сервер с указанными учётными данными и отвечает «✓ Сервер отвечает (HTTP 200)» или «✗ Нет подключения: …» с причиной.

Служба ведёт собственный журнал — файл logs\rusguard-service-log.txt в каталоге приложения, а её настройки хранятся в файле rusguard_config.json.

Запуск и остановка службы

Кнопки внизу окна относятся к службе той группы, раздел которой открыт: в разделах «Синхронизация пользователей» они управляют службой User Sync, в разделах «Синхронизация со СКУД» — службой PACS Sync. Рядом с кнопками — статус этой службы.

• «Сохранить» — записывает все параметры группы в файл настроек; в строке состояния появляется «✓ Параметры группы сохранены».
• «Запустить» — сначала сохраняет параметры, затем запускает службу; результат — «✓ Параметры сохранены, служба запущена». Первый цикл синхронизации начинается сразу, следующий — через заданный интервал. Кнопка доступна, только пока служба остановлена.
• «Остановить» — останавливает службу; начатый цикл прерывается, в строке состояния — «✓ Служба остановлена». Кнопка доступна, только пока служба запущена.
• Если в обязательном поле ошибка, сохранение не выполняется — список ошибок показывается в окне.

Службы зарегистрированы в Windows под именами «UnSpotAdScimService» и «UnSpotRusGuardService», поэтому запускать и останавливать их можно и из оснастки «Службы». Учтите: главный идентификатор сотрудника — адрес электронной почты. Если у пользователя в Active Directory он не заполнен, такой пользователь в UnSpot не попадёт.

Проверка и диагностика

Ход работы виден в журнале службы — файл logs\service-log.txt в каталоге приложения; открыть папку журналов можно кнопкой «Logs» в разделе службы. Служба PACS Sync пишет отдельный файл logs\rusguard-service-log.txt. В журнале User Sync записан каждый цикл: сколько групп и пользователей загружено из каталога, сколько получено из UnSpot, кто создан, обновлён и удалён, а также причины, по которым запись пропущена.

Запись в журнале	Что означает
Синхронизация групп отключена	В наборе полей не отмечены «Группы» — ни группы, ни их состав не синхронизируются
Поле FirstName или LastName пустое	У пользователя пусты источники имени или фамилии. При источниках givenName/sn имя и фамилия берутся из displayName, а если пуст и он — запись пропускается; при источниках «Display name …» отката нет: пустая часть displayName сразу означает пропуск записи
Email пользователя … не валидный	Значение выбранного почтового атрибута не похоже на адрес — служба подставляет userPrincipalName
Пользователь пропущен по фильтрации флагов в поле UAC	Запись отсеяна настройками «UAC содержит флаги» или «UAC НЕ содержит флаги»
Дубль пользователя AD, Дубль группы	Одна и та же запись пришла из двух подключений или совпала по почте либо названию. В UnSpot она заведена один раз
Ошибка при синхронизации …	Шаг цикла завершился ошибкой. Остальные шаги при этом выполняются, повтор произойдёт в следующем цикле

По умолчанию пишутся события уровня Info, файл ротируется раз в сутки, хранятся семь архивных копий. Для разбора проблемы можно включить подробный уровень: в файле NLog.config в каталоге приложения (для службы PACS Sync — rusguard_nlog.config) замените minlevel="Info" на minlevel="Debug" в правиле логирования для Release и перезапустите службу. В подробном режиме в журнал попадают тела запросов к UnSpot, то есть значения всех передаваемых полей, — верните прежний уровень сразу после диагностики.

Изменение настроек и удаление

Чтобы изменить параметры, отредактируйте поля и нажмите «Сохранить». Служба User Sync перечитывает файл настроек config.json перед каждым циклом, поэтому изменения применятся со следующего цикла; чтобы применить их сразу, остановите службу кнопкой «Остановить» и запустите снова кнопкой «Запустить». Служба PACS Sync применяет новые параметры из rusguard_config.json только после перезапуска.

Приложение удаляется стандартно — через «Параметры» → «Приложения». При удалении службы останавливаются и снимаются с регистрации, файлы настроек и папка журналов стираются. Файлы кэша cache.db и events.db остаются в каталоге приложения: если машина выводится из эксплуатации, удалите каталог целиком. Что лежит в этих файлах, описано в статье «Синхронизация из on-premise AD (LDAP-SCIM): как устроена».

Связанные статьи

• Синхронизация из on-premise AD (LDAP-SCIM): как устроена — вторая половина этой статьи: архитектура, состав передаваемых данных, хранение секретов и кэша.
• Синхронизация пользователей из внешней базы данных по ODBC (UnSpot ODBC SCIM Adapter) — родственный мост: сотрудники берутся не из AD, а из любой СУБД через ODBC.
• Обзор интеграций.