Синхронизация с Entra ID (Azure AD) через Graph API: как устроена

Если ваша компания использует облачный каталог Microsoft Entra ID (прежнее название — Azure AD), UnSpot может забирать данные сотрудников напрямую через Microsoft Graph API. Эта статья описывает, как устроен обмен: кто его инициирует, какие разрешения выдаются, что уходит из каталога в UnSpot и где хранятся токены доступа. Она адресована службе информационной безопасности, которая согласовывает использование интеграции. Как подключить и настроить синхронизацию, описано в статье «Настройка синхронизации с Entra ID (Azure AD) через Graph API».

Что делает эта синхронизация

Синхронизация односторонняя: данные переносятся из Entra ID в UnSpot, изменения в UnSpot обратно в каталог не записываются. Подключение выполняется в разделе Настройка → Интеграции → Синхронизации, карточка Entra ID (Azure AD). Настраивать интеграции могут роли Владелец и Администратор интеграций.

Обмен ключами и настройка провижининга на стороне Microsoft не требуются: администратор один раз авторизует учётную запись и выдаёт согласие на набор разрешений Graph. Дальше UnSpot обращается к каталогу от имени этой учётной записи.

Кто к кому подключается

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

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

Какие разрешения запрашиваются

При подключении UnSpot запрашивает у Microsoft Entra ID восемь делегированных разрешений. Разрешения делегированные, то есть действуют от имени авторизовавшей учётной записи и в пределах её собственных прав, а не от имени приложения.

Разрешение Graph	Что даёт
User.Read	Чтение профиля самой авторизовавшей учётной записи
User.Read.All	Чтение профилей всех пользователей каталога — на этом строится перенос карточек
Directory.Read.All	Чтение объектов каталога
Directory.AccessAsUser.All	Доступ к каталогу от имени авторизовавшего пользователя
Group.Read.All	Чтение групп каталога
GroupMember.Read.All	Чтение состава групп
Member.Read.Hidden	Чтение состава групп со скрытым членством
offline_access	Выдача refresh-токена, чтобы синхронизация продолжалась без повторного входа администратора

Разрешения уровня .All и Directory.AccessAsUser.All в Entra ID требуют согласия администратора. UnSpot это согласие не форсирует и не проверяет, какие разрешения фактически выданы: при неполном наборе подключение пройдёт, а синхронизация упадёт позже с ошибкой доступа. Это стоит учитывать при выдаче — соглашаться нужно на весь набор сразу.

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

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

Автоматическая синхронизация выполняется раз в сутки по расписанию платформы. Кнопки ручного запуска у этой интеграции в консоли нет — она есть только у подключений к локальному каталогу; существует служебный вызов API POST /user-sync/sync (роль «Администратор интеграций»), запускающий полный цикл. Дополнительно обмен запускается сразу после подключения, после добавления полей в набор и после изменения фильтра по группам; снятие отметки внеплановый обмен не запускает.

Внутри цикла UnSpot читает каталог постранично, по 999 записей за страницу, с паузой в секунду между страницами. Отдельной обработки ограничения частоты со стороны Microsoft нет: если Graph ответит отказом по превышению лимита, проход завершится ошибкой и повторится в следующем цикле. Ориентир по объёму: страница — это секунда паузы плюс сам запрос, каталог на несколько тысяч учётных записей читается за считаные минуты.

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

Набор полей задаёт администратор отметками в блоке «Данные для синхронизации». Адрес электронной почты, имя и фамилия переносятся всегда; остальные поля — только если отмечены.

Данные	Свойство Microsoft Graph	Когда передаются	Что появляется в UnSpot
Адрес электронной почты	userPrincipalName	всегда	Логин сотрудника. Свойство mail не запрашивается, поэтому в UnSpot попадает именно UPN — для тенантов с адресами вида …@company.onmicrosoft.com это заметная разница
Имя	givenName, иначе первая часть displayName, иначе часть адреса до @	всегда	Имя в карточке сотрудника
Фамилия	surname, иначе остаток displayName, иначе домен адреса	всегда	Фамилия в карточке сотрудника
Идентификатор записи	id (GUID)	всегда	Служебное поле: внешний идентификатор карточки
Признак активности	accountEnabled	всегда	Не передаётся в карточку. Используется как признак: отключённая в каталоге учётная запись архивируется в UnSpot
Подразделение	department	при отметке «Отдел»	Не поле «Отдел» карточки, а узел организационной структуры. Символ / в значении создаёт вложенные подразделения
Должность	jobTitle	при отметке «Должность»	Должность в карточке. Значение длиннее 128 символов обрезается
Телефон	mobilePhone	при отметке «Телефон»	Телефон в карточке. Рабочие телефоны businessPhones не запрашиваются
Руководитель	manager → userPrincipalName	при отметке «Руководитель»	Руководитель в карточке — только если его карточка уже есть в UnSpot и не архивирована
Фотография	фотография профиля, размер 240×240	при отметке «Аватар пользователя»	Аватар сотрудника. Уходит отдельным заданием платформы, не в общем цикле
Группы и их состав	id, displayName, onPremisesDomainName и участники	при отметке «Группы»	Группы UnSpot. К названию добавляется префикс локального домена, если он у группы указан

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

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

Выборка не различает членов организации и гостей: гостевые учётные записи B2B переносятся наравне с сотрудниками, а их логином становится UPN вида name_domain#EXT#@tenant.onmicrosoft.com. Если гостей в UnSpot быть не должно, исключите их фильтром по группам.

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

• Пароли и их хеши. Graph их не отдаёт, и UnSpot их не запрашивает. Пароль для входа в UnSpot генерируется случайным образом на стороне UnSpot.
• Данные из UnSpot обратно в Entra ID. Обратной записи нет: UnSpot не создаёт, не изменяет и не удаляет объекты каталога.
• Брони, расписание и действия сотрудников. Наружу они не уходят.
• Организационная структура каталога. Переносить её через Graph API интеграция не умеет — соответствующая отметка для этого способа запрещена на уровне продукта.
• Прочие свойства профиля: служебный телефон, кабинет, город и страна, табельный номер, лицензии, устройства и журналы входов не запрашиваются.

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

Все соединения инициирует облако UnSpot и все они исходящие. Со стороны клиента правил на межсетевом экране не требуется вовсе: обе стороны обмена находятся в облаках.

Что делает UnSpot	Куда идёт запрос
Получает и обновляет токен доступа	login.microsoftonline.com
Читает сотрудников, группы и состав групп	graph.microsoft.com
Читает фотографии сотрудников	graph.microsoft.com, отдельным заданием

Отдельно об уведомлениях Microsoft. В продукте есть механизм подписки на изменения каталога — он предполагает, что Microsoft обращается к UnSpot сам. В текущей версии подписки при подключении не создаются, а приходящие уведомления никакой синхронизации не запускают — обмен идёт только по расписанию. Для согласования это означает: входящих обращений от Microsoft к UnSpot интеграция не требует.

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

• Обмен идёт по HTTPS на порт 443 — и к login.microsoftonline.com, и к graph.microsoft.com. Оба адреса принадлежат Microsoft; UnSpot к другим узлам в рамках этой интеграции не обращается.
• Проверка сертификатов выполняется штатными средствами платформы; отключить её в приложении нельзя и настройки для этого нет.
• Авторизация — по стандарту OAuth 2.0, поток authorization code. Токен доступа передаётся заголовком по схеме Bearer.
• Адрес выдачи токена — общая точка входа Microsoft (common), конкретный тенант определяется по учётной записи, которая проходит вход.

Где хранятся токены

• Токен доступа и refresh-токен хранятся в базе данных рабочего пространства в открытом виде. Шифрование для этих полей не применяется — в отличие от пароля подключения к локальному каталогу, который шифруется.
• Наружу токены не отдаются: ни одна операция интерфейса их не возвращает.
• Срок жизни токена доступа задаёт Microsoft. Когда он истекает, UnSpot обновляет его по refresh-токену автоматически, без участия администратора.
• При ошибке подключения в журнал приложения записывается трассировка исключения, а в неё, в зависимости от настроек среды выполнения, могут попасть аргументы вызовов — включая значения токенов. Журналы доступны службе эксплуатации UnSpot, а не администратору рабочего пространства.

Компенсирующая мера на вашей стороне — регулярный пересмотр согласия приложения в центре администрирования Entra ID и отзыв доступа при смене подрядчика или ответственного администратора, а не расчёт на срок жизни токена.

Что кэшируется и что остаётся в UnSpot

Что	Где	Сколько живёт
Соответствие «идентификатор в Entra ID → карточка UnSpot»	служебная таблица базы данных рабочего пространства	пока подключена синхронизация. Удаляется при отключении и при переподключении
Соответствие «идентификатор группы → группа UnSpot»	служебная таблица	то же; при снятии отметки «Группы» соответствия и созданные группы остаются в UnSpot и перестают обновляться
Метка изменения фотографии	служебная таблица	используется, чтобы не скачивать неизменившееся фото повторно
Выборка сотрудников и групп текущего цикла	только в памяти процесса	до конца обработки задания, на диск не пишется

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

Что происходит, когда сотрудник исчезает из выборки

Механика единая для всех способов синхронизации, и её стоит разобрать до подключения. Сотрудник перестал попадать в выборку — его удалили из каталога, отключили учётную запись (accountEnabled = false) или он вышел за границы фильтра по группам — карточка в UnSpot архивируется:

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

Практическое следствие для фильтра по группам: исключение сотрудника из перечисленной в фильтре группы неотличимо для UnSpot от увольнения. Меняя состав таких групп в Entra ID, помните, что это отменяет брони.

Отдельно о группах: при отметке «Группы» UnSpot переносит все группы каталога — фильтр по группам на них не действует, он ограничивает только состав сотрудников. Состав групп UnSpot задаёт каталог: сотрудники, добавленные в такую группу вручную, будут из неё удалены при следующем цикле, а исчезнувшая в Entra ID группа удаляется и в UnSpot.

Как отозвать доступ

1. Со стороны Microsoft — удалить согласие приложения в центре администрирования Entra ID либо отключить учётную запись, выдавшую его. Обращаться в UnSpot для этого не нужно: следующий цикл синхронизации завершится ошибкой доступа, и подключение будет помечено недействительным.
2. Со стороны UnSpot — кнопка «Отключить» на карточке. Она останавливает синхронизацию и стирает настройки подключения вместе с токенами. Карточки сотрудников при этом сохраняются.

Учтите: отключение интеграции в UnSpot не отзывает выданное согласие на стороне Microsoft — согласие остаётся, пока его не удалят в Entra ID. Если цель в том, чтобы UnSpot гарантированно потерял доступ к каталогу, отзывать нужно именно на стороне Microsoft.

Что учесть при согласовании

1. Контур клиента в обмене не участвует. Ни входящих правил, ни доступа к локальной сети интеграция не требует — в этом её главное преимущество перед прямым подключением к локальному каталогу.
2. Выдаётся широкий набор разрешений на чтение каталога, включая состав групп со скрытым членством, и он требует согласия администратора Entra ID.
3. Токены хранятся в базе UnSpot без шифрования и могут попасть в журнал приложения при ошибке подключения.
4. Доступ отзывается на стороне Microsoft, и это единственный способ гарантированно его прекратить.
5. Изменение состава групп в фильтре архивирует сотрудников с отменой их броней и сессий.
6. Адресом сотрудника становится userPrincipalName, а не свойство mail: если они различаются, различие проявится в UnSpot.

Чем этот способ отличается от SCIM

	Graph API (эта статья)	SCIM 2.0
Кто инициирует обмен	UnSpot забирает данные	Entra ID отправляет данные
Где настраиваются правила	в UnSpot: набор полей и фильтр по группам	в Entra ID: назначение пользователей и групп, сопоставление атрибутов, область синхронизации
Что выдаётся	согласие на разрешения Graph	секретный токен UnSpot
Организационная структура	не переносится	переносится
Настройка на стороне Microsoft	не требуется	корпоративное приложение и провижининг
Подходит для других поставщиков	нет, только Entra ID	да — Okta, OneLogin и любой SCIM 2.0

Подключение через Graph API быстрее в настройке. Подключение по SCIM оставляет управление правилами в вашем каталоге и тем же механизмом работает с любым другим поставщиком идентификации. Выбирайте один способ, а не оба сразу — иначе у справочника будет два источника правды.

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

• Настройка синхронизации с Entra ID (Azure AD) через Graph API
• Синхронизация по SCIM 2.0 (Entra ID, Okta): как устроена
• Синхронизация пользователей с Active Directory (AD LDAP / OpenLDAP): как устроена
• Синхронизация пользователей с Google Workspace: как устроена
• Обзор интеграций
• Как выбрать способ синхронизации пользователей