Синхронизация из on-premise AD (LDAP-SCIM): как устроена

UnSpot AD SCIM — приложение, которое устанавливается в контуре клиента и переносит сотрудников и группы доступа из локальной Active Directory в UnSpot SaaS: каталог читается по протоколу LDAP, данные передаются в облако по стандарту SCIM. Эта статья описывает, как устроен обмен: кто его инициирует, что именно уходит в UnSpot и по какому каналу, где на машине лежат учётные данные и кэш и что за пределы вашего контура не выходит. Она адресована службе информационной безопасности, которая согласовывает использование интеграции. Как подключить и настроить сервис, описано в статье «Настройка синхронизации из on-premise AD (LDAP-SCIM)».

Что такое сервис синхронизации LDAP-SCIM

LDAP-SCIM — приложение, которое устанавливается в контуре клиента как служба Windows и синхронизирует пользователей и группы доступа из Active Directory (AD) в UnSpot. Из каталога данные читаются по протоколу LDAP (Lightweight Directory Access Protocol), в UnSpot передаются по протоколу SCIM (System for Cross-domain Identity Management). Решение рассчитано на перенос данных из on-premise систем в облако UnSpot SaaS в безопасном для клиента формате.

• каталог остаётся в вашем контуре: UnSpot не подключается к Active Directory ни напрямую, ни через шлюз;
• обмен ведёт служба, установленная у вас, и только она инициирует соединения;
• состав передаваемых данных ограничен полями, которые администратор отметил в настройках подключения.

Архитектура решения

Решение состоит из двух частей, которые ставятся одним установщиком в общий каталог (по умолчанию C:\Program Files\Umbrella IT\UnSpotAdScim).

• «UnSpot AD SCIM» — окно настройки для администратора. В нём задаются подключения к Active Directory и параметры обмена; всё введённое сохраняется в файл конфигурации config.json.
• «UnSpotAdScimService» — служба Windows, которая и выполняет синхронизацию. Она читает config.json в начале каждого цикла и работает без участия администратора: окно настройки для её работы не требуется и может быть закрыто.
• Подключений к Active Directory может быть несколько — по одному на каталог, у каждого свои сервер, учётная запись, фильтры и набор синхронизируемых полей. Пользователи и группы всех подключений сводятся в один список и уходят в одно рабочее пространство UnSpot.

Как проходит один цикл синхронизации

Служба работает циклами. Первый цикл начинается сразу после запуска службы, следующий — через заданный интервал после того, как предыдущий завершился. Это пауза между циклами, а не расписание по часам: время старта плавает вместе с длительностью синхронизации. Интервал задаётся в часах, от 1 до 1000, по умолчанию — 24; значение меньше 1 служба поднимает до одного часа.

В начале каждого цикла служба заново читает файл конфигурации, поэтому изменённые настройки применяются со следующего цикла.

Порядок синхронизации

1. Группы. Из каталога читаются группы доступа, из UnSpot — текущий список групп; расхождения применяются: создание, переименование, удаление.
2. Пользователи. То же самое для карточек сотрудников. Следом, если включена синхронизация оргструктуры, в UnSpot целиком передаётся дерево подразделений.
3. Вхождение пользователей в группы. Состав групп сверяется не с UnSpot, а с локальным кэшем (см. «Что кэшируется и где»), и в UnSpot уходят только изменения — кого добавить в группу и кого из неё убрать.

Шаги выполняются независимо друг от друга: ошибка на одном шаге записывается в журнал, и цикл продолжается со следующего шага. Повторных попыток внутри цикла нет — незавершённая работа выполняется в следующем цикле.

Как записи сопоставляются между AD и UnSpot

Главный ключ сопоставления — objectGUID объекта Active Directory: он записывается в UnSpot как внешний идентификатор записи и дальше опознаёт её в каждом цикле. Если совпадения по нему нет, служба ищет пользователя по адресу электронной почты (без учёта регистра), а группу — по названию. За счёт этого синхронизация «подхватывает» карточки, заведённые в UnSpot вручную, вместо того чтобы создавать дубли.

• Пользователь, у которого не заполнен выбранный почтовый атрибут, в синхронизацию не попадает: адрес электронной почты — обязательный признак записи.
• Если у пользователя пусты givenName или sn, имя и фамилия берутся из displayName; если пуст и он — запись пропускается.
• Пользователи и группы, которых больше нет в выборке из Active Directory, удаляются в UnSpot. Записи с пустым внешним идентификатором — то есть заведённые в UnSpot вручную, а не синхронизацией — при этом не трогаются; системные группы «All users» и «System» тоже не удаляются.
• Все создаваемые карточки помечаются активными. Признак «учётная запись отключена» в Active Directory сам по себе не блокирует сотрудника в UnSpot: отключённые учётные записи отсекаются только фильтром по флагам userAccountControl, если администратор его задал.

Что передаётся в UnSpot

Набор полей задаёт администратор в настройках подключения. Адрес электронной почты, имя и фамилия отмечены всегда и отключить их нельзя; остальные поля уходят в UnSpot, только если отмечены. Атрибут, из которого берётся почта, и атрибут номера пропуска администратор указывает сам.

Данные	Атрибут в Active Directory	Когда передаются	Что появляется в UnSpot
Адрес электронной почты	mail или userPrincipalName — атрибут выбирает администратор	всегда	Логин сотрудника. Приводится к нижнему регистру
Имя	givenName	всегда	Имя в карточке сотрудника
Фамилия	sn	всегда	Фамилия в карточке сотрудника
Идентификатор записи	objectGUID	всегда	Внешний идентификатор карточки — служебное поле, по нему запись опознаётся в следующих циклах
Подразделение	department	при отметке «Отдел»	Отдел в карточке сотрудника
Оргструктура	distinguishedName — путь собирается из компонентов OU	при отметке «Оргструктура»	Подразделение сотрудника в дереве оргструктуры. Отдельным запросом уходит и само дерево: путь подразделения, его описание и адрес почты руководителя
Руководитель	manager — по ссылке дополнительным запросом читается почтовый адрес руководителя	при отметке «Руководитель»	Руководитель в карточке сотрудника. В UnSpot передаётся именно адрес почты руководителя, а не его ФИО
Должность	title	при отметке «Должность»	Должность в карточке сотрудника
Рабочий телефон	telephoneNumber	при отметке «Телефон»	Телефон в карточке сотрудника, с типом «рабочий»
Номер пропуска	Атрибут, имя которого администратор задаёт сам	при отметке «Номер пропуска»	Номер пропуска в карточке сотрудника
Фотография	thumbnailPhoto	при отметке «Аватар»	Аватар сотрудника. Уходит отдельным запросом и только если изображение изменилось с прошлого цикла
Название и идентификатор группы	cn и objectGUID группы	при отметке «Группы»	Группа доступа в UnSpot. К названию добавляется префикс, если он задан в настройках подключения
Состав групп	member — список участников группы	при отметке «Группы»	Участники группы доступа

В терминах персональных данных за пределы вашего контура уходят: фамилия и имя, рабочий адрес электронной почты, рабочий телефон, должность, подразделение, номер пропуска в системе контроля доступа, фотография сотрудника и адрес почты его руководителя — и только те из них, что отмечены в настройках. Табельный номер, дата рождения, домашний адрес и другие кадровые сведения сервис не запрашивает и передать не может.

Что не передаётся

• Пароли и их хеши. Служба запрашивает у каталога строго перечисленный набор атрибутов, пароли в него не входят.
• Значение userAccountControl. Служба читает его, но использует только у себя — для отбора записей; в UnSpot оно не отправляется.
• Описание группы. Атрибут description у групп читается, но в UnSpot уходят только название и идентификатор группы.
• Остальное содержимое каталога. Атрибуты, не перечисленные в таблице выше, не запрашиваются: служба забирает из Active Directory ровно те поля, которые отмечены в настройках, плюс идентификатор и служебные userAccountControl и displayName.
• Данные из UnSpot обратно в Active Directory. Обратной записи нет: служба ничего не создаёт и не изменяет в каталоге, ей достаточно доступа на чтение.
• Брони, расписание и действия сотрудников в UnSpot. Служба их не запрашивает и никуда не передаёт.
• Входящие подключения. Служба не принимает соединений: в ней нет ни веб-сервера, ни прослушиваемого порта. UnSpot не знает её адреса и обратиться к ней не может.

Направление и инициатор обмена

Все соединения инициирует служба, установленная в вашем контуре. У облака UnSpot нет ни её адреса, ни учётных данных для входа в вашу сеть, поэтому входящие правила на межсетевом экране для этой интеграции не нужны.

Что делает служба	Куда идёт запрос
Читает пользователей, группы и подразделения	LDAP или LDAPS к контроллеру домена в вашей сети
Забирает текущие списки пользователей и групп из UnSpot, чтобы вычислить разницу	HTTPS к адресу SCIM вашего рабочего пространства
Создаёт, обновляет и удаляет карточки сотрудников и группы, меняет состав групп	HTTPS к тому же адресу
Передаёт фотографии сотрудников и дерево оргструктуры	HTTPS к тому же адресу

Обратный поток данных из UnSpot ограничен ответами на эти запросы: служба получает текущие карточки сотрудников и групп, чтобы сравнить их с каталогом, и идентификаторы только что созданных записей. Ничего другого — броней, расписаний, действий сотрудников — из UnSpot не приходит.

Протокол, порты и шифрование

В UnSpot данные уходят по HTTPS на порт 443. Адрес рабочего пространства вида https://ваш-домен.unspot.ru/api/scim администратор вводит в настройках; служба обращается только к нему. Тело запросов — JSON, авторизация — заголовком с секретным токеном по схеме Bearer. Сертификат сервера проверяется штатными средствами платформы: отключить проверку или доверять самоподписанному сертификату в приложении нельзя.

Запрос	Зачем
GET /Users, GET /Groups	Текущее состояние в UnSpot — постранично, по 20 записей
POST /Users, POST /Groups	Создание карточки сотрудника или группы
PATCH /Users/{id}, PATCH /Groups/{id}	Обновление полей, добавление и удаление участников группы
DELETE /Users/{id}, DELETE /Groups/{id}	Удаление карточки или группы
POST /Users/{id}/avatar	Фотография сотрудника, отдельным запросом
PUT /OrgUnits	Дерево подразделений целиком

К Active Directory служба обращается по LDAP на порт, указанный в настройках подключения: 389 для LDAP или 636 для LDAPS. В обоих случаях соединение аутентифицируется штатными механизмами Windows (Kerberos или NTLM). На порту 636 канал шифруется средствами TLS; на порту 389 включаются подпись и шифрование на уровне SASL — учётные данные и содержимое каталога по сети открытым текстом не идут. Для нестандартного порта требование шифрования администратор включает отдельным флажком.

Где хранятся учётные данные и токен

Все параметры службы, включая секреты, лежат в одном файле — config.json в каталоге приложения. В нём хранятся:

• логин и пароль учётной записи, под которой служба читает каталог, — своя пара на каждое подключение;
• секретный токен SCIM, выданный в UnSpot, и адрес рабочего пространства;
• корневой DN, фильтры, набор синхронизируемых полей и интервал синхронизации.

Пароли и токен хранятся в этом файле в открытом виде — приложение их не шифрует. Ограничьте доступ к каталогу приложения средствами операционной системы: читать config.json должны только администраторы машины и учётная запись, от которой работает служба. Смена пароля учётной записи Active Directory и ротация токена SCIM выполняются вручную — ни напоминаний, ни контроля срока в приложении нет.

В журнал работы секреты не попадают: при старте каждого цикла служба записывает туда конфигурацию, заменив пароль и токен звёздочками, а в сетевых запросах токен идёт только в заголовке авторизации.

Окно настройки требует прав локального администратора: при первом запуске оно регистрирует службу Windows «UnSpotAdScimService». Учётная запись для службы при регистрации не задаётся, поэтому служба работает от системной учётной записи компьютера (NT AUTHORITY\SYSTEM) и обладает на этой машине полными правами. Размещайте приложение на выделенной машине и не держите на ней посторонние задачи.

Что кэшируется и где

Рядом с приложением служба ведёт два файла базы данных SQLite. Оба лежат в каталоге приложения, срока жизни у записей нет — данные хранятся до перезаписи или до удаления файла.

Файл	Что внутри	Когда обновляется
cache.db	Две таблицы: состав групп — пары «идентификатор группы — идентификатор сотрудника» в терминах UnSpot — и контрольные суммы фотографий сотрудников. Имён, адресов и других персональных данных в файле нет	Состав групп перезаписывается целиком в конце каждого цикла; контрольная сумма фотографии — при её успешной отправке
events.db	Карточки сотрудников, полученные из UnSpot, в исходном виде: логин, ФИО, должность, телефон, подразделение, номер пропуска. Это персональные данные	Таблица очищается и заполняется заново в каждом цикле, сразу после чтения списка из UnSpot

Кэш состава групп определяет, что именно уходит в UnSpot на третьем шаге цикла: список участников сравнивается не с текущим состоянием в UnSpot, а с этим файлом. Очистить кэш можно единственным способом — вручную удалить файл cache.db в каталоге приложения; команды в интерфейсе для этого нет. После удаления служба в следующем цикле заново разошлёт все вхождения сотрудников в группы и повторно отправит фотографии.

При удалении приложения файл конфигурации и журналы стираются, а cache.db и events.db остаются в каталоге. Если машина выводится из эксплуатации, удаляйте каталог приложения целиком.

Журналы работы службы

Служба пишет журнал в файл logs\service-log.txt в каталоге приложения. Файл ротируется раз в сутки, хранятся семь архивных копий. По умолчанию записываются события уровня Info.

• начало и завершение каждого шага цикла, число записей, загруженных из каталога и полученных из UnSpot;
• имя и фамилия каждого обработанного сотрудника и адрес почты его руководителя;
• применённый фильтр LDAP и перечень запрошенных атрибутов;
• причина, по которой запись пропущена: нет имени и фамилии, некорректный адрес почты, отсев по флагам userAccountControl;
• ошибки создания, обновления и удаления записей.

Журнал содержит персональные данные сотрудников, поэтому доступ к каталогу приложения нужно ограничивать так же, как к файлу конфигурации. Пароль и токен в журнал не пишутся. Подробный уровень (Debug) включается вручную и добавляет в журнал тела запросов к UnSpot, то есть значения всех передаваемых полей, — включайте его только на время разбора инцидента, порядок описан в статье о настройке.

Требования к сети и правам

Что нужно	Подробности
Исходящий HTTPS	С машины, где работает служба, — доступ к адресу вашего рабочего пространства UnSpot по порту 443. Входящие правила не нужны: соединения всегда открывает служба
Доступ к контроллеру домена	С той же машины — LDAP на порт 389 или LDAPS на порт 636
Права в Active Directory	Достаточно учётной записи с правом чтения нужной ветки каталога: служба только читает и ничего в каталоге не меняет. Заведите для интеграции отдельную учётную запись и ограничьте её область тем DN, который указан в настройках подключения, — этот пароль хранится на диске в открытом виде
Права на машине	Локальный администратор — для установки приложения и регистрации службы. Сама служба работает от системной учётной записи компьютера
Права в UnSpot	Секретный токен SCIM создаёт в карточке «SCIM 2.0» «Владелец» или «Администратор интеграций»
Изоляция машины	На машине в открытом виде лежат пароль от каталога и токен UnSpot, а журналы содержат персональные данные. Ограничьте доступ к каталогу приложения средствами NTFS и круг администраторов этой машины

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

• Настройка синхронизации из on-premise AD (LDAP-SCIM) — вторая половина этой статьи: подключение, установка, поля формы, запуск службы.
• Справочник SCIM API UnSpot — описание всех SCIM-эндпоинтов и атрибутов.
• Синхронизация пользователей с Active Directory (AD LDAP / OpenLDAP): как устроена — прямое подключение UnSpot к каталогу, без моста.
• Настройка синхронизации с Active Directory (AD LDAP / OpenLDAP) — пошаговое подключение прямой синхронизации.
• Обзор интеграций.