Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

SCIM provisioning в Microsoft Entra ID

View as MarkdownEdit this pageReport an issueSet up docs MCP
Возможность тарифа Enterprise

SCIM доступна в тарифе Enterprise. Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.

ClickHouse Cloud поддерживает SCIM 2.0 (System for Cross-domain Identity Management) для автоматизированного управления жизненным циклом пользователей и групп. После подключения к провайдеру идентификации каждый пользователь, которого вы назначаете приложению ClickHouse Cloud, автоматически создаётся в вашей организации с нужной ролью, обновления профиля синхронизируются автоматически, а удаление пользователя из IdP лишает его доступа — без ручных приглашений и неактивных аккаунтов.

В этом руководстве описана сквозная настройка SCIM provisioning с Microsoft Entra ID (ранее Azure Active Directory). Конечная точка SCIM ClickHouse Cloud соответствует SCIM 2.0 (RFC 7644). Entra ID аутентифицируется в этой конечной точке с помощью долгоживущего Bearer-токена, который формируется из ключа и секрета SCIM-токена, созданных в консоли ClickHouse Cloud.

Перед началом работы

Вам потребуется:

  • Роль Admin в организации ClickHouse Cloud.
  • Настроенная SAML SSO между Entra ID и ClickHouse Cloud. SCIM создаёт учётные записи пользователей, а вход в них выполняется через SAML, поэтому SSO необходимо настроить заранее.
  • Доступ к центру администрирования Microsoft Entra с ролью не ниже Application Administrator (или Cloud Application Administrator) и разрешением на настройку подготовки пользователей в корпоративном приложении.
  • Список ролей, которые нужно назначать через SCIM (например: Admins, Developers, Read-only). Определите его заранее — в Entra ID потребуется создать соответствующие группы.

Как SCIM работает с ClickHouse Cloud

  1. Администратор Entra ID назначает пользователя — напрямую или через группу — корпоративному приложению ClickHouse Cloud.
  2. Служба подготовки Entra ID обращается к конечной точке SCIM ClickHouse Cloud по HTTPS, используя для аутентификации созданный вами Bearer-токен.
  3. ClickHouse Cloud создаёт пользователя в вашей организации и назначает роли на основе его членства в группах Entra ID.
  4. Пользователь входит в ClickHouse Cloud через существующий процесс SAML SSO.
  5. Изменения профиля и групп, а также деактивация в Entra ID автоматически передаются в ClickHouse Cloud.

Настройка SCIM в организации ClickHouse Cloud

Включите SCIM

Войдите в ClickHouse Cloud консоль как администратор организации и откройте Настройки организации → Настройки SAML и SCIM → SCIM Configuration.

Нажмите Enable SCIM. SCIM становится доступен после подключения SAML SSO. Если этот параметр неактивен, сначала завершите настройку SAML.

Будет сгенерирован SCIM endpoint URL следующего вида:

https://api.clickhouse.cloud/v1/organizations/<your-org-id>/scim

Скопируйте его — позже вы вставите его в Entra ID в качестве Tenant URL.

Создайте токен доступа SCIM

Найдите раздел Generate new key и выберите дату истечения срока действия.

Нажмите Generate new key. Токен отображается только один раз: ключ с префиксом scim_ и секрет. Сразу скопируйте оба значения и сохраните их в защищённом менеджере секретов — позднее получить их будет невозможно. Если вы их потеряете, отзовите токен и создайте новый.

Для Entra ID объедините ключ и секрет в один Bearer-токен следующего вида:

<scim-key>:<scim-secret>

То есть ключ токена, начинающийся с scim_, затем двоеточие и секрет токена — без пробелов. Entra ID отправляет это значение в заголовке Authorization: Bearer при каждом запросе.

Настройте сопоставление ролей

На панели SCIM Configuration нажмите Map roles in "Users and roles" (либо перейдите напрямую через Пользователи и роли → Роли).

Группы SCIM связываются с ролями ClickHouse Cloud по имени. Следует учитывать несколько правил:

  • Нельзя сопоставить группу SCIM с предопределённой системной ролью. Сопоставления SCIM применяются только к пользовательским ролям. Если вам нужно предоставить возможность системного уровня через SCIM, создайте пользовательскую роль с необходимыми разрешениями.
  • Совпадающие имена связываются автоматически. Если пользовательская роль имеет то же имя, что и входящая группа SCIM, ClickHouse Cloud связывает их автоматически — ручное сопоставление не требуется.
  • Чтобы использовать имя роли, отличающееся от имени группы, создайте пользовательскую роль с нужным именем, затем укажите в её поле SCIM group имя группы SCIM, с которой она должна быть связана.
  • Несопоставленные группы создают новые роли. Если Entra ID отправляет группу, имя которой не совпадает с именем существующей роли и которая не указана в поле SCIM group какой-либо роли, ClickHouse Cloud создаёт новую пользовательскую роль с именем этой группы. Затем вы можете предоставить ей необходимые разрешения.

Настройка подготовки пользователей в Microsoft Entra ID

Откройте корпоративное приложение ClickHouse Cloud

Откройте страницу обзора Microsoft Entra ID и в разделе Manage левого меню выберите Корпоративные приложения. Откройте приложение, созданное при настройке SAML SSO для ClickHouse Cloud.

Если вы ещё не создали корпоративное приложение, сначала следуйте руководству по настройке SAML SSO — при SSO на основе SAML одно и то же корпоративное приложение используется и для единого входа, и для SCIM provisioning.

Настройте режим подготовки и учетные данные

На левой панели приложения выберите Provisioning, затем нажмите Get started (или Provisioning → Edit provisioning).

Установите для Provisioning Mode значение Automatic. В разделе Admin Credentials укажите:

  • Tenant URL — URL конечной точки SCIM из ClickHouse Cloud Console (URL вида .../scim).
  • Secret Token — учетные данные SCIM, объединенные двоеточием, в формате <scim-key>:<scim-secret>. Entra ID отправляет их в заголовке Authorization: Bearer.

Нажмите Test Connection. Entra ID выполнит тестовый запрос к конечной точке SCIM; должно появиться уведомление об успешном выполнении. Если запрос завершится ошибкой, перейдите к разделу Troubleshooting.

Нажмите Save.

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

После сохранения учётных данных разверните раздел Mappings. Entra ID отобразит два набора сопоставлений:

  • Provision Microsoft Entra ID Users
  • Provision Microsoft Entra ID Groups

Откройте Provision Microsoft Entra ID Users и убедитесь, что сопоставления атрибутов соответствуют требованиям ClickHouse Cloud.

По умолчанию Entra ID сопоставляет userName с userPrincipalName. Важно, чтобы userName формировался из атрибута, содержащего тот же адрес электронной почты, который используется для входа через SAML SSO; конкретное имя атрибута не имеет значения. В некоторых тенантах userPrincipalName уже содержит этот адрес электронной почты и ничего менять не нужно; в других он хранится в mail, поэтому следует изменить сопоставление, чтобы userName формировался из mail. Чтобы изменить источник, выберите строку userName, укажите правильный Source attribute и сохраните изменения.

Установите Matching precedence так, чтобы userName был основным атрибутом для сопоставления. Неподдерживаемые сопоставления можно удалить; всё, что не входит в стандартный набор SCIM, игнорируется на стороне ClickHouse Cloud.

Остальные строки сопоставляются по умолчанию — убедитесь, что все они настроены:

Атрибут Microsoft Entra ID Атрибут ClickHouse Cloud (SCIM) Обязательный
mail emails[type eq "work"].value Да — должен совпадать с userName
givenName name.givenName Рекомендуется
surname name.familyName Рекомендуется
displayName displayName Рекомендуется — отображается в интерфейсе ClickHouse Cloud
Switch([IsSoftDeleted], ...) active Да — отвечает за деактивацию

Откройте Provision Microsoft Entra ID Groups и убедитесь, что displayName сопоставлен с displayName, а members — с members: отображаемое имя группы связывается с ролью ClickHouse Cloud.

Настройте область подготовки пользователей

Разверните раздел Settings:

  • Установите для Scope значение Sync only assigned users and groups. Это ограничит подготовку пользователями и группами, которые вы явно назначите приложению на следующем шаге.
  • Пока оставьте для Provisioning Status значение Off — вы включите его после назначения тестовых пользователей.

Нажмите Save.

Назначьте группы и пользователей

Здесь роли назначаются автоматически.

Создайте группы в Entra ID. Для каждого ранее настроенного сопоставления ролей создайте или найдите группу Entra ID с точно таким же отображаемым именем. Например, если в сопоставлении указано ClickHouse-Admins → Admin, создайте в Entra ID группу с именем ClickHouse-Admins.

Назначьте группы приложению. В корпоративном приложении перейдите в раздел Users and groups → Add user/group, выберите группу роли и назначьте её приложению. Повторите это для каждой группы ролей. Поскольку область подготовки приложения настроена на assigned users and groups, подготавливаются только эти группы и их участники.

Назначьте пользователей. Доступны два варианта:

  • Через группы (рекомендуется). Добавьте пользователей в группы Entra ID, назначенные приложению. Они будут подготовлены в ClickHouse Cloud, а соответствующая роль будет назначена автоматически.
  • Напрямую. Назначьте отдельных пользователей приложению в разделе Users and groups. Им будет назначена роль Default role, если только они также не входят в назначенную группу.

Назначение через группы удобнее для дальнейшего управления: если чья-либо роль меняется, достаточно обновить состав группы.

Включите подготовку к работе

Вернитесь в раздел Provisioning, установите для Provisioning Status значение On и нажмите Save.

Entra ID выполняет подготовку пользователей регулярно, примерно каждые 40 минут. Чтобы немедленно подготовить конкретного пользователя — например, для тестирования — выберите Provisioning → Provision on demand, найдите пользователя и запустите однократную подготовку.

Проверьте интеграцию

После включения подготовки используйте Provision on demand, чтобы сразу синхронизировать одного или двух тестовых пользователей, не дожидаясь следующего цикла. Затем вернитесь в Settings → Users and roles в консоли ClickHouse Cloud и убедитесь, что синхронизированные пользователи появились с ожидаемыми ролями.

Протестируйте эти шаги на одном или двух пользователях до назначения всей команды. Если какой-либо шаг не применяется, используйте Provision on demand, чтобы принудительно запустить синхронизацию, затем обратитесь к разделу Устранение неполадок.

# Действие в Entra ID Ожидаемый результат в ClickHouse Cloud
1 Добавьте тестового пользователя в группу ClickHouse-Admins и выполните Provision on demand Пользователь появится в Settings → Members с ролью Admin
2 Тестовый пользователь входит в ClickHouse Cloud через SSO Он попадает на панель мониторинга с правами администратора
3 Обновите имя пользователя в Entra ID и повторно выполните подготовку Обновлённое имя появится в Members
4 Переместите пользователя из ClickHouse-Admins в ClickHouse-Read-only и повторно выполните подготовку Его роль изменится на Read-only
5 Отмените назначение пользователя приложению (или отключите аккаунт в Entra ID) Пользователь будет удалён из организации; последующие попытки входа завершатся ошибкой

Если какой-либо шаг завершается ошибкой, устраните её причину, прежде чем продолжить: проблемы обычно накапливаются.

Рекомендации для продакшна

Регулярно меняйте токены

Установите напоминание в календаре о ротации SCIM-токенов. Рекомендуемая периодичность: каждые 12 месяцев или сразу после ухода из компании администратора, знавшего токен. ClickHouse Cloud позволяет иметь по два активных токена для каждой организации, чтобы выполнять ротацию без нарушения процесса подготовки: сгенерируйте новый токен, обновите Secret Token в Entra ID, проверьте подключение с помощью Test Connection, затем отзовите старый токен.

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

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

Проверяйте журнал аудита

Каждое действие SCIM — создание или деактивация пользователя, обновление профиля — фиксируется в журнале аудита ClickHouse Cloud. См. Журнал аудита. Периодически проверяйте журнал, особенно после массового выделения ресурсов.

Установите безопасную роль по умолчанию

Если пользователь Entra ID назначен приложению, но не входит ни в одну из назначенных групп, ему назначается роль по умолчанию. Выберите роль с минимально необходимыми правами, которая всё же позволяет пользователю что-то делать, чтобы ошибки конфигурации не снижали безопасность.

Не используйте одновременно SCIM и ручные приглашения

После включения SCIM управляйте участниками через Entra ID — не отправляйте тем же пользователям ручные приглашения. Совмещение этих двух подходов приводит к путанице в вопросе об источнике истины и может создавать дубликаты.

Учитывайте цикл подготовки

Синхронизация Entra ID выполняется регулярно (примерно каждые 40 минут), поэтому обычные изменения применяются не сразу. Если изменение нужно применить немедленно, используйте Provision on demand и отслеживайте повторяющиеся сбои в Provisioning logs.

Устранение неполадок

"Проверка подключения" завершается ошибкой в Entra ID
  • Убедитесь, что SCIM включен в консоли ClickHouse Cloud.
  • Убедитесь, что значение Tenant URL в Entra ID точно совпадает с URL конечной точки SCIM, указанным в Cloud Console, — идентификатор организации должен быть указан верно.
  • Убедитесь, что Secret Token имеет вид <scim-key>:<scim-secret>: ключ (начинающийся с scim_), двоеточие и затем секрет. Не добавляйте пробелы в начале или конце и не указывайте префикс Bearer (Entra ID добавляет его автоматически).
  • Если вы выполняли ротацию токенов, убедитесь, что используете новый ключ и секрет, а не предыдущую пару.
Пользователи создаются, но не имеют разрешений
  • Проверьте, что для нужной роли добавлена строка в разделе Map roles in "Users and roles".
  • Проверьте, что имя группы Entra ID точно совпадает с именем группы SCIM в сопоставлении, включая регистр и дефисы.
  • Если в вашей конфигурации некоторые пользователи намеренно создаются без группы, убедитесь, что задана роль по умолчанию.
Пользователи или группы вообще не подготавливаются
  • Убедитесь, что для Provisioning Status задано значение On.
  • Убедитесь, что для Scope задано значение Sync only assigned users and groups, а пользователи и группы действительно назначены приложению в разделе Users and groups.
  • Помните, что цикл выполняется примерно каждые 40 минут — используйте Provision on demand, чтобы сразу проверить одного пользователя.
  • Для подготовки групп, а не только их участников, требуется Microsoft Entra ID P1 или более поздняя версия.
Дублирующийся пользователь в списке участников

Обычно это вызвано различием в регистре адреса электронной почты между Entra ID и ранее отправленным вручную приглашением. Удалите дубликат из списка Members, затем отмените назначение пользователя в Entra ID и назначьте его снова (или повторно запустите Provision on demand), чтобы выполнить подготовку заново.

Подготовка группы завершается ошибкой из-за несовпадения имени

Отображаемое имя группы в Entra ID не соответствует настроенному сопоставлению в ClickHouse Cloud. Переименуйте группу Entra ID или добавьте сопоставление в разделе Map roles in "Users and roles" на панели SCIM Configuration (либо через Users and roles → Roles).

Деактивированные пользователи по-прежнему отображаются как участники

Деактивация вступит в силу в следующем цикле подготовки. Чтобы применить ее немедленно, используйте Provision on demand для этого пользователя. Если после этого пользователь все еще остается участником, проверьте Provisioning → View provisioning logs на наличие ошибки при операции деактивации.

Я выполнил ротацию токена SCIM, и теперь Entra ID выдает ошибку

Убедитесь, что вы обновили Secret Token в нужном корпоративном приложении Entra ID, указав значение в виде <scim-key>:<scim-secret>. После обновления нажмите Test Connection для проверки. Когда подготовка снова будет выполняться без ошибок, отзовите старый токен в консоли ClickHouse Cloud.

Я потерял токен SCIM

Токены невозможно восстановить. В разделе Organization settings → SAML and SCIM settings → SCIM Configuration консоли ClickHouse Cloud отзовите утерянный токен и создайте новый, затем обновите Secret Token в Entra ID.

Часто задаваемые вопросы

Нужна ли SAML SSO для использования SCIM?

Да. SCIM создаёт учётные записи пользователей, а ClickHouse Cloud аутентифицирует их через SAML. Сначала настройте SAML SSO.

Можно ли использовать одно корпоративное приложение для SAML и SCIM?

Да. При SSO на основе SAML одно корпоративное приложение Entra ID обеспечивает как единый вход, так и SCIM provisioning.

Почему Secret Token имеет формат key:secret?

Entra ID аутентифицируется, передавая Secret Token в заголовке Authorization: Bearer. Конечная точка SCIM ClickHouse Cloud ожидает, что значением bearer будут ключ и секрет токена, разделённые двоеточием.

Как быстро изменения в Entra ID появляются в ClickHouse Cloud?

Entra ID выполняет provisioning примерно каждые 40 минут. Чтобы немедленно обновить данные, используйте Provision on demand для нужного пользователя.

Где получить помощь, если возникли проблемы?

Откройте обращение в службу поддержки через ClickHouse Cloud консоль (Help → Contact support) и укажите:

  • идентификатор организации;
  • название и идентификатор объекта корпоративного приложения Entra ID;
  • снимок экрана с записью об ошибке из Provisioning → View provisioning logs.
Navigation