Настройка синхронизации с Entra ID (Azure AD) через Graph API
Инструкция для администратора UnSpot и администратора Microsoft Entra ID: как подключить синхронизацию сотрудников из облачного каталога Entra ID (Azure AD) через Microsoft Graph API, какие поля перенести и как ограничить выборку. Подключение выполняется в разделе Настройка → Интеграции → Синхронизации. Настраивать интеграции могут роли Владелец и Администратор интеграций. Как устроен обмен, какие разрешения выдаются и что уходит из каталога — в парной статье «Синхронизация с Entra ID (Azure AD) через Graph API: как устроена»; её же передают службе информационной безопасности на согласование.
Что понадобится
- Роль в UnSpot: Владелец или Администратор интеграций.
- Учётная запись Microsoft с правом читать каталог организации — например, глобальный администратор. Обмен дальше идёт от её имени, поэтому её отключение остановит синхронизацию.
- Возможность выдать согласие администратора на разрешения Graph: часть из них уровня
.All, и без согласия администратора они не действуют. - Свободный слот синхронизации: одновременно может быть подключён только один способ — Entra ID, Google Workspace, AD LDAP или OpenLDAP. Если подключён другой, сначала отключите его.
Шаг 1. Подключение
- Перейдите в Настройка → Интеграции → Синхронизации и нажмите «Подключить» в карточке Entra ID (Azure AD).
- Откроется окно авторизации Microsoft. Войдите под учётной записью с правом читать каталог организации и подтвердите запрошенные разрешения.
- После авторизации Microsoft вернёт вас в UnSpot, карточка покажет подключённый аккаунт, и синхронизация сотрудников запустится сразу.
Видео записано в старом интерфейсе — названия пунктов могли измениться, порядок действий прежний, включая окно разрешений Microsoft:
Если согласие выдано не полностью, подключение всё равно пройдёт, а синхронизация упадёт позже с ошибкой доступа. Поэтому подтверждайте весь набор разрешений сразу — UnSpot не проверяет, какие из них фактически выданы.
Шаг 2. Данные для синхронизации
Email, имя и фамилия переносятся всегда. Остальные поля включаются кнопкой «Изменить» на карточке — до подключения набор полей не редактируется.
| Отметка в форме | Что переносится |
|---|---|
| Отображаемое имя | Свойство displayName из Microsoft Graph. Отметка появилась 31.08.2026 и по умолчанию выключена; она есть только в окне «Настройки синхронизации» по кнопке «Изменить» — при первом подключении через окно Microsoft набор полей не выбирается. Значение переносится как есть, без разбора на слова и без фоллбэков: если displayName в каталоге пуст, поле в карточке будет затёрто. Пока отметка снята, поле не трогается. Включённая отметка делает поле «Отображаемое имя» в карточке сотрудника нередактируемым |
| Отдел | Свойство department. Попадает не в поле «Отдел» карточки, а в организационную структуру: значение становится узлом дерева, а символ / создаёт вложенные подразделения |
| Телефон | Свойство mobilePhone. Служебные телефоны (businessPhones) не переносятся |
| Должность | Свойство jobTitle, значение длиннее 128 символов обрезается |
| Руководитель | Свойство manager. Связь строится по адресу почты, поэтому карточка руководителя тоже должна быть в UnSpot и не быть архивной |
| Аватар пользователя | Фотография профиля. Обновляется отдельным заданием платформы — сразу после включения отметки аватары не появятся |
| Группы | Группы каталога переносятся в группы UnSpot. Отметка доступна только после подключения |
Отметки «Организационная структура» в форме этой интеграции нет — Graph API дерево не переносит; при попытке включить поле через API UnSpot вернёт ошибку «Некорректные данные для синхронизации». Подразделения наполняются из поля «Отдел».
Отметки NumberPass в форме этой интеграции нет — она есть только у AD LDAP и OpenLDAP. Номер пропуска через Graph API не передаётся; поле существует лишь на уровне API, и включение его там обнулит значения в карточках. Если номер пропуска вам нужен, заполняйте его другим способом.
Перенос групп имеет два следствия, о которых стоит знать заранее. Переносятся все группы каталога, а не только те, что указаны в фильтре. И состав группы задаёт каталог: сотрудники, добавленные в синхронизированную группу вручную, будут удалены из неё при следующем цикле.
Шаг 3. Фильтр по группам
Чтобы синхронизировать не весь каталог, нажмите «Изменить» на карточке. В поле «Группы» введите идентификаторы групп Entra ID через запятую, и выберите режим:
- «Синхронизировать пользователей» — в UnSpot попадут только участники перечисленных групп;
- «Не синхронизировать пользователей» — участники перечисленных групп будут исключены, остальные синхронизированы.
| Ограничение | Значение |
|---|---|
| Сколько групп можно указать | от 1 до 10 на сервере. Поле в форме ограничено 255 символами — на практике около шести идентификаторов. Пустое поле не отклоняется, а снимает фильтр: синхронизироваться будет весь каталог |
| Какие участники учитываются | только прямые. Вложенные группы не раскрываются: участник дочерней группы в выборку не попадёт |
| На что действует фильтр | только на сотрудников. Группы переносятся все |
| Когда применяется | после выгрузки каталога, на стороне UnSpot |
Идентификатор группы смотрите в центре администрирования Microsoft Entra: раздел Groups → карточка группы → поле Object ID. Изменение фильтра сразу запускает пересинхронизацию сотрудников.
⚠️ Сужая фильтр, помните: исключённые сотрудники не просто перестают обновляться, а архивируются — с отменой всех их броней, сессий и закреплённых мест. Механика описана в парной статье «…: как устроена».
Настройка фильтра по группам в старом интерфейсе:
Что доступно после подключения
Карточка показывает подключённый аккаунт. Дальше синхронизация идёт автоматически — раз в сутки по расписанию платформы. Кнопки ручного запуска у этой интеграции нет: она есть только у подключений к локальному каталогу.
Созданные синхронизацией сотрудники писем от UnSpot не получают: пароль задаётся случайно и никому не сообщается. Вход для них — через SSO Microsoft (если настроен) или восстановление пароля по адресу почты.
| Кнопка | Когда доступна | Что делает |
|---|---|---|
| Изменить | когда подключение исправно | Открывает настройки: набор полей и фильтр по группам. Добавление поля или изменение фильтра сразу запускает пересинхронизацию; снятие отметки вступает в силу со следующего цикла, уже перенесённые значения остаются в карточках |
| Переподключить | только когда подключение помечено недействительным — на карточке появляется сообщение «Эта учетная запись недействительна. Пожалуйста, переподключите свой аккаунт или используйте другой» | Проводит авторизацию заново. Настройки и связи между записями каталога и карточками UnSpot при этом стираются, объекты сопоставляются заново по адресам почты |
| Отключить | всегда | Останавливает синхронизацию и стирает настройки вместе с токенами. Карточки сотрудников и созданные группы сохраняются. Согласие приложения на стороне Microsoft при этом не отзывается — если нужно именно это, удалите его в центре администрирования Entra |
Что выбрать: Graph API или SCIM
Для Entra ID в UnSpot есть два способа синхронизации, и они отличаются тем, где живут правила.
| Graph API (эта статья) | SCIM 2.0 | |
|---|---|---|
| Что настраивается | только авторизация в UnSpot | корпоративное приложение и провижининг в Entra ID |
| Кто инициирует обмен | UnSpot забирает данные | Entra ID отправляет данные |
| Где задаются правила | в UnSpot: набор полей и фильтр по группам | в Entra ID: назначение пользователей и групп, сопоставление атрибутов, область синхронизации |
| Организационная структура | не переносится | переносится |
| Работает с другими поставщиками | нет | да — Okta, OneLogin и любой SCIM 2.0 |
| Что быстрее настроить | этот способ | — |
Используйте один способ, а не оба сразу: технически включить их вместе можно, но у справочника появится два источника правды.
Если что-то не работает
| Что видите | В чём причина | Что делать |
|---|---|---|
| «Указанная учетная запись не поддерживается для синхронизации. Проверьте разрешение на использование учетной записи» | Microsoft отклонил подключение — обычно не выданы разрешения уровня .All | Повторите подключение и подтвердите весь набор разрешений; при необходимости выдайте согласие администратора в центре администрирования Entra |
| «Эта учетная запись недействительна…» | Токен перестал действовать: у авторизовавшей учётной записи сменился пароль, её отключили или отозвали согласие приложения | Нажмите «Переподключить» и авторизуйтесь заново |
| «Синхронизация пользователей уже подключена (используется другая служба каталогов)» | Уже подключён другой способ синхронизации | Отключите текущий способ, затем подключайте этот |
| «Некорректные данные для синхронизации» | Поле «Организационная структура» передано через API — в форме этой интеграции такой отметки нет | Для Graph API она недоступна — используйте отметку «Отдел» |
| Ошибка при попытке подключить Entra ID поверх AD LDAP или OpenLDAP | Переключение между этими способами без предварительного отключения обрабатывается некорректно | Сначала нажмите «Отключить» на текущем подключении, дождитесь обновления карточки и только потом подключайте Entra ID |
| Синхронизировались не все сотрудники | Сработал фильтр по группам: учитываются только прямые участники, вложенные группы не раскрываются | Перечислите дочерние группы явно или снимите фильтр |
| У сотрудников не тот адрес почты | Адресом становится userPrincipalName, а не свойство mail | Если они различаются, приведите UPN в соответствие на стороне Entra ID |
| Аватары не появились | Фотографии обновляются отдельным заданием платформы | Дождитесь следующего запуска задания |
| Синхронизация словно замерла, карточка исправна | Ошибки цикла в консоль не выводятся | Признак — в отчёте «История управления пользователями» перестали появляться записи с инициатором «синхронизация»; сами ошибки пишутся в служебный журнал платформы, упомяните это при обращении в поддержку |
Историю изменений, сделанных синхронизацией, видно в разделе Аналитика → Отчёты, отчёт «История управления пользователями»: у таких записей в поле инициатора стоит признак синхронизации.
