Настройка синхронизации по SCIM 2.0 (Entra ID, Okta)

Инструкция для администратора UnSpot и администратора поставщика идентификации: как настроить провижининг сотрудников в UnSpot по стандарту SCIM 2.0. Работает с Microsoft Entra ID (прежнее название — Azure AD), Okta, OneLogin и любым другим каталогом с поддержкой SCIM 2.0. Подключение выполняется в разделе Настройка → Интеграции → Синхронизации. Как устроен обмен, что даёт выданный токен и что хранится на стороне UnSpot — в парной статье «Синхронизация по SCIM 2.0 (Entra ID, Okta): как устроена»; её же передают службе информационной безопасности на согласование.

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

• Роль в UnSpot: Владелец или Администратор интеграций.
• Права администратора в вашем поставщике идентификации — для создания корпоративного приложения и настройки провижининга.
• Решение о приветственных письмах: отправлять ли их сотрудникам, созданным через SCIM. Тумблер настраивается при подключении.
• Решение о сроке действия токена: «Без ограничения» либо от 1 до 24 месяцев.
• Настроенная исходящая подписка на событие «Проблемы синхронизаций» — без неё предупреждение об истечении токена не придёт никому. Настраивается в Настройка → Интеграции → Исходящие подписки.

Отдельный слот синхронизации для SCIM не нужен: он работает независимо от подключений к AD LDAP, Entra ID и Google Workspace. Но включать SCIM одновременно с одним из них не стоит — у справочника будет два источника правды.

Шаг 1. Включите SCIM в UnSpot

1. Перейдите в Настройка → Интеграции → Синхронизации и нажмите «Подключить» в карточке SCIM 2.0.
2. Скопируйте SCIM URL (вида https://вашдомен.unspot.ru/api/scim) и токен — оба значения вы введёте в настройках поставщика идентификации.
3. Задайте «Срок работы токена»: «Без ограничения» либо от 1 до 24 месяцев.
4. При необходимости включите «Отправлять приветственные письма» — созданным через SCIM сотрудникам придёт письмо с краткой инструкцией.

⚠️ Сохраните токен сразу. Он показывается один раз, при создании подключения; получить его повторно невозможно. Любой, у кого есть этот токен, может не только создавать сотрудников, но и прочитать весь справочник вашего рабочего пространства.

⚠️ Срок действия и тумблер писем задаются только в момент подключения. После закрытия окна вернуться к этим настройкам через интерфейс нельзя — на карточке остаётся только кнопка «Отключить».

Шаг 2. Настройка Microsoft Entra ID

Примечание: видео ниже записаны в старом интерфейсе портала — названия пунктов меню могли измениться, порядок действий прежний.

1. Откройте центр администрирования Microsoft Entra и создайте Enterprise application (корпоративное приложение).
2. В боковом меню приложения выберите Provisioning и режим Automatic.
3. В поле Tenant URL вставьте SCIM URL из UnSpot, в поле Secret token — токен, затем нажмите Test Connection и дождитесь успешной проверки.
4. Сохраните настройки провижининга.

Сопоставление атрибутов

1. В разделе Provision Microsoft Entra ID Groups откройте «Show advanced options» → Edit attribute list и проверьте атрибуты групп.
2. В разделе Provision Microsoft Entra ID Users замените исходный атрибут mailNickname на objectId — он сопоставляется с externalId в UnSpot.

Итоговый набор исходных атрибутов пользователя:

• userPrincipalName
• Switch([IsSoftDeleted], "False", "True", "True", "False")
• jobTitle
• givenName
• surname
• telephoneNumber
• objectId
• department

Телефон передавайте с типом work — значения с другим типом UnSpot отклоняет. Учтите также: деактивация через SCIM сотрудника, у которого в UnSpot роль администратора, не применяется — таких пользователей деактивируют вручную.

Область синхронизации

• Синхронизировать только назначенных: назначьте приложению пользователей и группы (Users and Groups), затем в Provisioning выберите «Sync only assigned users and groups» и запустите провижининг.
• Синхронизировать всех: в Provisioning выберите «Sync all users and groups», сохраните и запустите провижининг.

Шаг 2 (альтернатива). Okta и другие SCIM 2.0

С UnSpot работает любой поставщик идентификации, поддерживающий SCIM 2.0 с авторизацией по Bearer-токену: Okta, OneLogin и другие. Логика одинаковая: в настройках провижининга приложения укажите SCIM URL из UnSpot в качестве базового адреса и токен в качестве Bearer-credentials, затем настройте сопоставление атрибутов и область синхронизации.

Требование	Значение
Адрес сотрудника	передаётся в userName
Заголовок формата	для операций записи обязателен Content-Type: application/scim+json; при application/json запрос отклоняется
Схема авторизации	Bearer — с учётом регистра
Участники групп	задаются идентификаторами UnSpot, а не внешними идентификаторами вашего каталога. Неизвестный идентификатор приводит к ошибке
Телефон	только с типом work

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

Что происходит при синхронизации

• Новые пользователи из области синхронизации создаются в UnSpot — при включённом тумблере с приветственным письмом.
• Изменения профиля (имя, должность, телефон, отдел) обновляются автоматически.
• Помеченные неактивными в каталоге деактивируются в UnSpot: отменяются их брони, удаляются сессии и календари, снимаются закреплённые места, парковка и права делегата.
• Удалённые в каталоге архивируются — дополнительно обнуляется внешний идентификатор и сотрудник исключается из всех групп и команд.
• Группы создаются, их состав поддерживается в актуальном состоянии.
• Организационная структура передаётся в одну сторону — из каталога в UnSpot. Это полная замена дерева: подразделения, которых нет в присланном наборе, удаляются вместе с ветвью. Операция доступна не чаще раза в час.

Срок действия токена

Карточка SCIM 2.0 показывает состояние токена: «Дата прекращения работы токена» и сколько осталось дней, либо «Бессрочно».

Предупреждение приходит только в день истечения и только подписчикам исходящей подписки на событие «Проблемы синхронизаций». Запаса «за неделю» нет. Если подписка не настроена, уведомление не уйдёт никому — настройте её заранее в Настройка → Интеграции → Исходящие подписки.

После истечения карточка показывает «Работа токена была прекращена», а все обращения вашего каталога отклоняются. Отдельной операции «перевыпустить токен» нет: нужно нажать «Отключить» и подключить SCIM заново, а затем обновить токен в настройках поставщика идентификации.

⚠️ Отключение SCIM обнуляет внешние идентификаторы у всех сотрудников и групп рабочего пространства. После повторного подключения ваш каталог заново сопоставит объекты с карточками UnSpot по адресам почты. Планируйте перевыпуск как обслуживание.

Справочник SCIM API

Полное описание эндпоинтов с примерами запросов и ответов — в статье «Справочник SCIM API UnSpot». Кратко:

Метод	Эндпоинт	Назначение
GET	/api/scim/Schemas	Описание SCIM-схем
GET / POST	/api/scim/Users	Список и создание пользователей
GET / PUT / PATCH / DELETE	/api/scim/Users/{id}	Чтение и изменение пользователя
POST	/api/scim/Users/{id}/avatar	Загрузка аватара (JPEG или PNG, до 100 КБ)
GET / POST	/api/scim/Groups	Список и создание групп
GET / PUT / PATCH / DELETE	/api/scim/Groups/{id}	Чтение и изменение группы
PUT	/api/scim/OrgUnits	Загрузка организационной структуры

Если что-то не работает

Что видите	В чём причина	Что делать
Отказ с кодом 401	Токен отсутствует, неверен либо схема авторизации написана в другом регистре	Проверьте заголовок авторизации в настройках поставщика: схема пишется как Bearer, с заглавной буквы
Отказ с кодом 400 и сообщением об истёкшем токене	Срок действия токена закончился. Это именно 400, а не 401 — многие поставщики показывают такую ошибку как «неверный запрос»	Отключите SCIM и подключите заново, затем обновите токен в настройках поставщика
Отказ с кодом 415	Операция записи отправлена с заголовком Content-Type: application/json	Укажите application/scim+json
Ошибка при создании пользователя, упоминающая externalId	Такой внешний идентификатор уже используется другой карточкой	Проверьте сопоставление objectId → externalId на стороне каталога
Ошибка «Manager is not correct»	Руководитель не найден в UnSpot	Убедитесь, что карточка руководителя создаётся раньше подчинённых
Ошибка при добавлении участника в группу	Участники задаются идентификаторами UnSpot, а не внешними идентификаторами каталога	Проверьте, что все участники уже созданы в UnSpot
Отказ при загрузке оргструктуры с просьбой попробовать позже	Операция доступна не чаще раза в час	Повторите позже
Из UnSpot пропали подразделения	Загрузка оргструктуры — полная замена дерева: отсутствующие в наборе узлы удаляются	Отправляйте дерево целиком, а не изменившуюся часть
Деактивация администратора не применяется	Для пользователя с ролью администратора в UnSpot операция игнорируется	Деактивируйте такого сотрудника вручную в UnSpot
Ошибки провижининга в Entra ID	Атрибут не прошёл валидацию	Откройте журналы провижининга в центре администрирования Entra: там видно, какой именно

Историю на стороне UnSpot смотрите в разделе Аналитика → Отчёты, отчёт «История управления пользователями»: операции SCIM отмечены соответствующим признаком у инициатора действия. Отчёт «История управления интеграциями» события SCIM не фиксирует.

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

• Синхронизация по SCIM 2.0 (Entra ID, Okta): как устроена
• Справочник SCIM API UnSpot
• Настройка синхронизации с Entra ID (Azure AD) через Graph API
• Настройка синхронизации из on-premise AD (LDAP-SCIM)
• Обзор интеграций