Синхронизация пользователей с Google Workspace: как устроена

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

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

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

Достаточно один раз авторизовать учётную запись Google с доступом к каталогу организации — обычно суперадминистратора Workspace. Дальше UnSpot обращается к каталогу от её имени.

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

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

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

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

Какие права выдаются

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

Разрешение	Что даёт	Тип
admin.directory.user.readonly	Чтение карточек сотрудников каталога	только чтение
admin.directory.orgunit.readonly	Чтение организационных подразделений	только чтение
userinfo.email	Адрес учётной записи, которая выдала согласие	только чтение
admin.directory.orgunit	Создание, изменение и удаление организационных подразделений	запись

Четвёртое разрешение — на запись, и это нужно назвать прямо. В коде UnSpot нет ни одного обращения, которое создавало бы, изменяло или удаляло подразделения в Google Workspace: используются только операции чтения. Но право выдаётся вместе с остальными и живёт в токене, поэтому при согласовании его следует учитывать как выданное, а не как неиспользуемое. Компенсирующая мера — периодический пересмотр прав приложения в консоли администратора Google и отзыв доступа при смене ответственного администратора.

Служебная учётная запись с делегированием полномочий домена (service account с domain-wide delegation) не используется: доступ выдаётся согласием живого администратора по OAuth 2.0. Отдельный «расширенный набор прав» для организационной структуры не существует — все четыре разрешения запрашиваются одинаково; при подключении UnSpot проверяет, что Google вернул их все, и отказывает, если набор урезан.

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

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

Каталог читается постранично, по 500 записей за страницу. Обработки ограничения частоты со стороны Google нет: если Google ответит отказом по превышению лимита, проход завершится ошибкой и повторится в следующем цикле. Ориентир по объёму: страница — 500 записей, каталог на несколько тысяч учётных записей читается за минуты.

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

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

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

Данные	Поле Google Directory	Когда передаются	Что появляется в UnSpot
Адрес электронной почты	первый адрес из списка emails	всегда	Логин сотрудника. Берётся именно первый адрес списка, а не тот, что помечен основным, — если у сотрудника несколько адресов, значение может отличаться от ожидаемого
Имя	name.givenName	всегда	Имя в карточке. Если поле пусто, подставляется часть адреса почты до символа @
Фамилия	name.familyName	всегда	Фамилия в карточке. Если поле пусто, подставляется имя домена без доменной зоны
Идентификатор записи	id	всегда	Служебное поле: внешний идентификатор карточки. Пока связь живёт, сопоставление держится на нём — смена адреса почты в Workspace не создаёт дубля, адрес в UnSpot просто обновится
Признак приостановки	suspended	всегда	Не передаётся в карточку. Используется как признак: приостановленная в Workspace учётная запись архивируется в UnSpot
Подразделение	organizations[0].department	при отметке «Отдел»	Отдел сотрудника. Взаимоисключается с переносом организационной структуры
Организационная структура	orgUnitPath и дерево подразделений каталога	один раз — в момент включения отметки «Организационная структура»	Дерево подразделений UnSpot и привязка сотрудника к узлу; суточный цикл обновляет только привязку к уже существующим узлам, новые подразделения сами не появятся. Руководитель подразделения не переносится
Должность	organizations[0].title	при отметке «Должность»	Должность в карточке. Значение длиннее 128 символов обрезается
Телефон	phones[0].value	при отметке «Телефон»	Телефон в карточке — первый номер из списка
Руководитель	relations[0].value — первая запись списка «Отношения» независимо от её типа: проверьте, что отношение «Руководитель» стоит в списке первым	при отметке «Руководитель»	Руководитель в карточке — только если его карточка уже есть в UnSpot, не архивирована и не деактивирована
Фотография	фотография профиля сотрудника	при отметке «Аватар пользователя»	Аватар сотрудника. Уходит отдельным заданием платформы, не в общем цикле

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

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

• Пароли и их хеши. Разрешений на доступ к данным безопасности учётных записей UnSpot не запрашивает. Пароль для входа в UnSpot генерируется случайным образом на стороне UnSpot.
• Почта, календарь, файлы и любые другие сервисы Google. Выданные разрешения относятся только к каталогу: ни Gmail, ни Google Календарь, ни Диск в них не входят. Календарные подключения UnSpot — отдельная интеграция с отдельным согласием.
• Группы Google Workspace. Они не переносятся вообще: разрешение на чтение групп не запрашивается, а перенос групп для этого способа отключён на уровне продукта.
• Пользовательские (кастомные) схемы каталога. Дополнительные поля, заведённые администратором Workspace, не запрашиваются.
• Данные из UnSpot обратно в Google. Обратной записи нет.
• Брони, расписание и действия сотрудников. Наружу они не уходят.

Отдельно: состояние «архивная учётная запись» в Workspace UnSpot не обрабатывает — учитывается только «приостановлена». Архивный в Workspace сотрудник останется активным в UnSpot.

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

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

Что делает UnSpot	Куда идёт запрос
Получает и обновляет токен доступа	служба авторизации Google
Читает сотрудников и подразделения	Google Admin SDK, Directory API
Читает фотографии сотрудников	тот же интерфейс, отдельным заданием

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

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

• Обмен идёт по HTTPS на порт 443 к интерфейсам Google. К другим узлам в рамках этой интеграции UnSpot не обращается.
• Проверка сертификатов выполняется штатными средствами платформы; отключить её в приложении нельзя и настройки для этого нет.
• Авторизация — по стандарту OAuth 2.0, поток authorization code с запросом офлайн-доступа: выдаётся refresh-токен, чтобы синхронизация продолжалась без повторного входа администратора.

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

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

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

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

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

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

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

Механика единая для всех способов синхронизации. Сотрудник удалён из каталога или его учётная запись приостановлена — карточка в UnSpot архивируется:

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

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

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

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

Отключение интеграции в UnSpot не отзывает выданное согласие на стороне Google. Если цель в том, чтобы UnSpot гарантированно потерял доступ к каталогу, отзывать нужно именно в консоли администратора Google.

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

1. Контур клиента в обмене не участвует — ни входящих правил, ни доступа к локальной сети интеграция не требует.
2. Синхронизируются все домены организации Workspace. Выборка идёт по организации (customer), которой принадлежит выдавший согласие администратор: учётные записи дополнительных и дочерних доменов переносятся тоже, а не только домен администратора.
3. Среди выданных прав есть право на изменение организационных подразделений Google Workspace. Код им не пользуется, но оно выдано.
4. Токены хранятся в базе UnSpot без шифрования.
5. Синхронизируется весь каталог организации — фильтра выборки у этой интеграции нет.
6. Группы Workspace не переносятся вообще — если вы рассчитываете использовать их в правах доступа UnSpot, этот способ не подойдёт.
7. Токен сессии администратора передаётся в адресной строке при старте подключения.
8. Приостановка учётной записи архивирует сотрудника с отменой его броней и сессий; состояние «архивная» в Workspace не обрабатывается.
9. Доступ отзывается на стороне Google, и это единственный способ гарантированно его прекратить.

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

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