Синхронизация по SCIM 2.0 (Entra ID, Okta): как устроена
SCIM 2.0 (System for Cross-domain Identity Management) — стандартный протокол провижининга: ваш поставщик идентификации сам создаёт, обновляет и деактивирует сотрудников в UnSpot. Так работают Microsoft Entra ID, Okta, OneLogin и любой другой каталог с поддержкой SCIM 2.0. Эта статья описывает, как устроен обмен: кто его инициирует, что даёт выданный токен, что принимается и что хранится на стороне UnSpot. Она адресована службе информационной безопасности, которая согласовывает использование интеграции. Как подключить и настроить — в статье «Настройка синхронизации по SCIM 2.0 (Entra ID, Okta)».
Что такое провижининг по SCIM
При подключении по SCIM источником правды остаётся ваш каталог: поставщик идентификации отправляет изменения в UnSpot по защищённому соединению с секретным токеном. Новые сотрудники появляются в UnSpot автоматически, изменения профилей подтягиваются, уволенные деактивируются, группы и организационная структура поддерживаются в актуальном состоянии.
Подключение включается в разделе Настройка → Интеграции → Синхронизации, карточка SCIM 2.0. Настраивать интеграции могут роли Владелец и Администратор интеграций.
Отличие от прямых подключений принципиальное. При синхронизации с AD LDAP, Entra ID через Graph API или Google Workspace инициатором выступает UnSpot: он обращается к вашему каталогу и хранит доступ к нему. Здесь наоборот — обращается ваш каталог, а наружу отдаётся секрет UnSpot. Это не «более безопасный» вариант, а другой профиль риска: вместо доступа к вашей сети появляется долгоживущий ключ на чтение и запись справочника сотрудников.
Кто к кому подключается
SCIM работает независимо от остальных способов синхронизации: в отличие от прямых подключений, которые исключают друг друга, провижининг можно включить одновременно с любым из них. Технически это возможно, но означает два источника правды для одного справочника — включать оба одновременно не стоит.
Что даёт секретный токен
Это ключевой пункт для согласования, и он часто понимается неверно. Токен выдаётся для того, чтобы каталог мог создавать сотрудников, но права им даются шире.
| Что можно сделать с токеном | Подробности |
|---|---|
| Прочитать весь справочник сотрудников | Запрос списка возвращает всех пользователей рабочего пространства, включая деактивированных, до 1000 записей за один запрос. В выдаче: адрес почты, имя и фамилия, должность, телефон, подразделение, ФИО и идентификатор руководителя, роль в UnSpot, номер пропуска, кадровый номер, признак активности, норма посещения и режим работы (workMode — только чтение) |
| Создавать, изменять и удалять сотрудников | Стандартные операции SCIM над пользователями |
| Создавать, изменять и удалять группы | Включая полную замену состава группы |
| Заменять дерево организационной структуры | Одной операцией, целиком — см. раздел ниже |
| Загружать фотографии сотрудников | Форматы JPEG и PNG, размер до 100 КБ |
Иными словами, SCIM-подключение не является операцией «только на запись». Утечка токена означает утечку справочника сотрудников с персональными данными и возможность массово изменить состав пользователей рабочего пространства. Компенсирующие меры: хранить токен в защищённом хранилище настроек каталога, задавать конечный срок его действия и планово перевыпускать.
Токен хранится в базе данных рабочего пространства в открытом виде — без хеширования и без шифрования. Повторно получить его через интерфейс нельзя: он показывается один раз, при создании подключения.
Жизненный цикл токена
Срок действия задаётся при подключении: «Без ограничения» либо от 1 до 24 месяцев. Карточка SCIM 2.0 показывает дату прекращения работы токена и сколько осталось дней либо надпись «Бессрочно».
Предупреждение об истечении работает не так, как обычно ожидают. Письмо уходит только в последний день работы токена — весь этот день токен ещё действует, а в письме названа дата, с которой он перестанет приниматься, — однократно, и только получателям исходящей подписки на событие «Проблемы синхронизаций» (Настройка → Интеграции → Исходящие подписки). Если такая подписка не настроена, о приближении срока не узнает никто. Запаса «за неделю» или «за месяц» нет; если рассылка в этот день не отработала, повторной попытки не будет.
После истечения все эндпоинты SCIM отвечают отказом, провижининг останавливается, а карточка показывает «Работа токена была прекращена».
Перевыпуск токена стоит дороже, чем кажется. Отдельной операции «выпустить новый токен» нет: подключение нужно удалить и создать заново. Удаление подключения обнуляет внешние идентификаторы у всех сотрудников и всех групп рабочего пространства, поэтому после перевыпуска ваш каталог заново сопоставляет объекты с карточками UnSpot по адресам электронной почты. Планируйте перевыпуск как обслуживание, а не как замену строки в настройках.
Что передаётся в UnSpot
Состав данных определяет ваш каталог: UnSpot принимает то, что ему отправляют, в пределах поддерживаемого набора атрибутов.
| Атрибут SCIM | Поле UnSpot | Обязательность |
|---|---|---|
userName | Адрес электронной почты — он же логин | обязателен |
name.givenName | Имя | обязателен |
name.familyName | Фамилия | обязателен |
externalId | Внешний идентификатор карточки | необязателен, до 36 символов, уникален |
title | Должность | необязателен |
phoneNumbers с типом work | Телефон | необязателен; другой тип отклоняется с ошибкой |
active | Признак активности сотрудника | необязателен, по умолчанию активен |
расширение enterprise, department | Подразделение в оргструктуре | необязателен |
расширение enterprise, manager.value | Руководитель | необязателен; ищется по идентификатору или адресу почты, при неудаче — ошибка |
расширение UnSpot, role | Роль в UnSpot | необязателен |
расширение UnSpot, numberPass | Номер пропуска (СКУД) | необязателен |
расширение UnSpot, employeeId | Кадровый номер | необязателен |
расширение UnSpot, orgUnit | Подразделение; приоритетнее department | необязателен |
расширение UnSpot, attendance | Норма посещения офиса — целое от 0 до 100 | необязателен |
Персональные данные, которые принимает и хранит UnSpot: фамилия и имя, адрес электронной почты, телефон, должность, подразделение, связь с руководителем, номер пропуска и кадровый номер. Состав определяете вы на стороне каталога — UnSpot не требует передавать больше, чем адрес почты, имя и фамилию.
Что не принимается и не хранится
- Пароли. Атрибут
passwordиз запроса не читается вовсе. Пароль для входа в UnSpot генерируется случайным образом на стороне UnSpot. - Массив
emails. Адрес берётся только изuserName; переданные вemailsзначения игнорируются. - Прочие стандартные атрибуты SCIM — отображаемое имя, локаль, часовой пояс, адреса, фотографии в профиле, сертификаты — не поддерживаются и молча отбрасываются без ошибки.
- Обратной передачи в ваш каталог нет. UnSpot не инициирует ни одного исходящего соединения в рамках этой интеграции.
Направление и инициатор обмена
Обмен односторонний по инициативе: ваш каталог → UnSpot, входящие запросы по защищённому соединению. UnSpot к вашему каталогу не обращается и его учётных данных не хранит.
Со стороны клиента нужны исходящие правила на межсетевом экране: служба провижининга вашего каталога должна иметь доступ к адресу рабочего пространства UnSpot. Если каталог облачный (Entra ID, Okta), запросы идут из облака поставщика, и правила на вашем периметре не требуются вовсе.
Протокол, аутентификация и лимиты
| Параметр | Значение |
|---|---|
| Адрес | Вида https://ваш-домен.unspot.ru/api/scim — выдаётся при подключении |
| Протокол | HTTPS. Адрес всегда формируется со схемой HTTPS |
| Аутентификация | Секретный токен в заголовке по схеме Bearer. Проверка схемы чувствительна к регистру |
| Формат тела | Для операций записи обязателен Content-Type: application/scim+json. При application/json запрос отклоняется |
| Отсутствующий или неверный токен | Отказ с кодом 401 |
| Истёкший токен | Отказ с кодом 400, а не 401 — это частая причина неверной диагностики на стороне каталога |
| Ограничение частоты запросов | Отсутствует. Ограничение действует только для операции замены оргструктуры — не чаще раза в час |
Эндпоинты SCIM вынесены из-под общей аутентификации приложения и доступны в сети публично: единственная защита — секретность токена. Компенсирующие меры на вашей стороне: конечный срок действия токена, плановый перевыпуск и, если ваш поставщик это поддерживает, ограничение исходящих адресов службы провижининга.
Организационная структура
Дерево подразделений загружается одной операцией. Вложенность поддерживается: путь разбирается по символу /, промежуточные узлы создаются автоматически, у подразделения можно указать описание и адрес почты руководителя.
Это полная замена дерева, а не дополнение. Узлы, которые были созданы синхронизацией и отсутствуют в присланном наборе, удаляются вместе со всей ветвью. Отправка неполного дерева приведёт к удалению недостающих подразделений в UnSpot.
Операция ограничена одним вызовом в час на рабочее пространство: повторный вызов раньше срока отклоняется. Наборы больше 500 элементов — или любые наборы, когда синхронизированное дерево в UnSpot уже больше 500 узлов, — обрабатываются асинхронно — ответ приходит сразу, а дерево перестраивается фоном.
Что происходит при деактивации и удалении
| Что делает каталог | Что происходит в UnSpot |
|---|---|
Помечает сотрудника неактивным (active: false) | Деактивация. Отменяются брони, удаляются сессии и токены доступа, календари, брони ячеек хранения, снимаются закреплённые места, парковка и права делегата |
| Удаляет сотрудника | Архивация — если у сотрудника нет записи другой синхронизации. Дополнительно к перечисленному выше обнуляются внешний идентификатор и связь с руководителем, сотрудник исключается из всех групп, команд и списка избранных мест. Сама запись не удаляется. Исключение: если личный календарь сотрудника подключён к переговорной, запрос на удаление отклоняется, пока календарь не отключат |
| Удаляет группу | Группа удаляется. Системную группу удалить нельзя |
| Заменяет состав группы | Состав приводится к присланному. Участники задаются идентификаторами UnSpot, а не внешними идентификаторами каталога |
Отдельная особенность: попытка деактивировать через SCIM сотрудника с ролью «Владелец» молча игнорируется — операция завершается успешно, но изменения не применяются; точно так же игнорируется и активация Владельца через SCIM. Остальные административные роли (интеграций, офисов, пользователей) SCIM деактивирует как обычных сотрудников. Владельцев деактивируют вручную в UnSpot.
Журналы и аудит
- Операции записи по SCIM журналируются: тип операции, поддомен рабочего пространства и идентификатор объекта. Значения персональных данных и токен в журнал не пишутся — при ошибке валидации фиксируются только имена полей.
- Операции чтения не журналируются вовсе. Запрос списка сотрудников следа не оставляет — это стоит учитывать при оценке рисков утечки токена.
- Изменения сотрудников видны в отчёте «История управления пользователями» (Аналитика → Отчёты) с признаком SCIM у инициатора действия. В отчёте хранятся ФИО и адрес почты затронутого сотрудника, действие и перечень изменённых полей; срок хранения — год.
- Подключение, изменение и отключение SCIM в отчёт «История управления интеграциями» не попадают — этот отчёт наполняется другими событиями.
Одно слепое пятно: удаление по SCIM сотрудника, у которого есть запись облачной синхронизации, деактивирует карточку без записи в «Истории управления пользователями» — внутреннее событие деактивации бизнес-журнал не слушает. Деактивация через active: false в отчёт попадает — как обновление карточки.
Что учесть при согласовании
- UnSpot не получает доступа в ваш контур и не хранит учётных данных вашего каталога — в этом главное преимущество способа.
- Взамен наружу выдаётся токен, дающий чтение всего справочника сотрудников с персональными данными и полный контроль над составом пользователей.
- Токен хранится в базе UnSpot в открытом виде, ограничения частоты запросов к эндпоинтам нет, операции чтения не журналируются.
- Предупреждение об истечении приходит только в день истечения и только подписчикам события «Проблемы синхронизаций» — подписку нужно настроить заранее.
- Перевыпуск токена обнуляет внешние идентификаторы всех сотрудников и групп.
- Замена оргструктуры удаляет отсутствующие в наборе подразделения вместе с ветвью.
- Правила синхронизации остаются в вашем каталоге — назначение пользователей, сопоставление атрибутов и область синхронизации UnSpot не контролирует.
Токен может назначать роли. Расширение role принимает любые роли UnSpot, включая «Владелец», — ограничений на стороне UnSpot нет. Учитывайте это, решая, кому доверить настройку провижининга у поставщика.
