Skip to main content
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.
Используете Okta?Если ваш провайдер идентификации — Okta, воспользуйтесь руководством SCIM provisioning с Okta. Настройка на стороне ClickHouse Cloud идентична; отличается только конфигурация IdP.

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

Вам потребуется:
  • Роль 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

1

Включите SCIM

Войдите в ClickHouse Cloud консоль как администратор организации и откройте Настройки организации → Настройки SAML и SCIM → SCIM Configuration.Нажмите Enable SCIM. SCIM становится доступен после подключения SAML SSO. Если этот параметр неактивен, сначала завершите настройку SAML.Будет сгенерирован SCIM endpoint URL следующего вида:
Скопируйте его — позже вы вставите его в Entra ID в качестве Tenant URL.
2

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

Найдите раздел Generate new key и выберите дату истечения срока действия.
Запланируйте ротациюРекомендуем установить срок действия 12 месяцев и добавить напоминание в календарь. ClickHouse Cloud поддерживает до двух активных токенов SCIM одновременно, поэтому ротацию можно выполнить без простоя: создайте новый токен, переключите Entra ID на него, убедитесь, что подготовка пользователей по-прежнему работает, затем отзовите старый токен.
Нажмите Generate new key. Токен отображается только один раз: ключ с префиксом scim_ и секрет. Сразу скопируйте оба значения и сохраните их в защищённом менеджере секретов — позднее получить их будет невозможно. Если вы их потеряете, отзовите токен и создайте новый.Для Entra ID объедините ключ и секрет в один Bearer-токен следующего вида:
То есть ключ токена, начинающийся с scim_, затем двоеточие и секрет токена — без пробелов. Entra ID отправляет это значение в заголовке Authorization: Bearer при каждом запросе.
3

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

На панели 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

1

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

Откройте страницу обзора Microsoft Entra ID и в разделе Manage левого меню выберите Корпоративные приложения. Откройте приложение, созданное при настройке SAML SSO для ClickHouse Cloud.Если вы ещё не создали корпоративное приложение, сначала следуйте руководству по настройке SAML SSO — при SSO на основе SAML одно и то же корпоративное приложение используется и для единого входа, и для SCIM provisioning.
2

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

На левой панели приложения выберите 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.
3

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

После сохранения учётных данных разверните раздел 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.
Используйте тот же адрес электронной почты, что и для SAML SSOЗначение, передаваемое в userName, должно совпадать с адресом электронной почты, который каждый пользователь использует для входа через SAML SSO. SCIM создаёт аккаунт, а SAML аутентифицирует пользователя. Поэтому, если userName SCIM и адрес электронной почты в утверждении SAML не совпадают, SAML при входе создаст отдельного пользователя, которым SCIM не управляет, — появится дублирующий неуправляемый аккаунт. Сопоставьте userName с атрибутом (userPrincipalName, mail или другим), содержащим тот же адрес электронной почты, который передаёт ваша конфигурация SAML.
Остальные строки сопоставляются по умолчанию — убедитесь, что все они настроены:Откройте Provision Microsoft Entra ID Groups и убедитесь, что displayName сопоставлен с displayName, а members — с members: отображаемое имя группы связывается с ролью ClickHouse Cloud.
Регистр адресов электронной почты имеет значениеУбедитесь, что значения, передаваемые в userName и основной адрес электронной почты, имеют одинаковый регистр. ClickHouse Cloud приводит адреса электронной почты к нижнему регистру; различия между этими двумя полями могут привести к сбоям подготовки.
4

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

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

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

Здесь роли назначаются автоматически.Создайте группы в Entra ID. Для каждого ранее настроенного сопоставления ролей создайте или найдите группу Entra ID с точно таким же отображаемым именем. Например, если в сопоставлении указано ClickHouse-Admins → Admin, создайте в Entra ID группу с именем ClickHouse-Admins.Назначьте группы приложению. В корпоративном приложении перейдите в раздел Users and groups → Add user/group, выберите группу роли и назначьте её приложению. Повторите это для каждой группы ролей. Поскольку область подготовки приложения настроена на assigned users and groups, подготавливаются только эти группы и их участники.
Для подготовки групп требуется соответствующая лицензия Entra IDДля подготовки самих групп, а не только их участников, требуется Microsoft Entra ID P1 или выше. При подготовке групп сама группа создаётся в ClickHouse Cloud и связывается с соответствующей ролью по отображаемому имени.
Назначьте пользователей. Доступны два варианта:
  • Через группы (рекомендуется). Добавьте пользователей в группы Entra ID, назначенные приложению. Они будут подготовлены в ClickHouse Cloud, а соответствующая роль будет назначена автоматически.
  • Напрямую. Назначьте отдельных пользователей приложению в разделе Users and groups. Им будет назначена роль Default role, если только они также не входят в назначенную группу.
Назначение через группы удобнее для дальнейшего управления: если чья-либо роль меняется, достаточно обновить состав группы.
6

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

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

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

После включения подготовки используйте Provision on demand, чтобы сразу синхронизировать одного или двух тестовых пользователей, не дожидаясь следующего цикла. Затем вернитесь в Settings → Users and roles в консоли ClickHouse Cloud и убедитесь, что синхронизированные пользователи появились с ожидаемыми ролями. Протестируйте эти шаги на одном или двух пользователях до назначения всей команды. Если какой-либо шаг не применяется, используйте Provision on demand, чтобы принудительно запустить синхронизацию, затем обратитесь к разделу Устранение неполадок. Если какой-либо шаг завершается ошибкой, устраните её причину, прежде чем продолжить: проблемы обычно накапливаются.
Где искать ошибки SCIM в Entra IDОшибки SCIM отображаются в приложении на странице Provisioning → View provisioning logs (также доступной по пути Identity → Monitoring & health → Provisioning logs). В каждой записи указаны запрос, целевой объект и ошибка, дословно возвращённая ClickHouse Cloud. Начните проверку с неё.

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

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

Установите напоминание в календаре о ротации 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.

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

  • Убедитесь, что 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 на наличие ошибки при операции деактивации.
Убедитесь, что вы обновили Secret Token в нужном корпоративном приложении Entra ID, указав значение в виде <scim-key>:<scim-secret>. После обновления нажмите Test Connection для проверки. Когда подготовка снова будет выполняться без ошибок, отзовите старый токен в консоли ClickHouse Cloud.
Токены невозможно восстановить. В разделе Organization settings → SAML and SCIM settings → SCIM Configuration консоли ClickHouse Cloud отзовите утерянный токен и создайте новый, затем обновите Secret Token в Entra ID.

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

Да. SCIM создаёт учётные записи пользователей, а ClickHouse Cloud аутентифицирует их через SAML. Сначала настройте SAML SSO.
Да. При SSO на основе SAML одно корпоративное приложение Entra ID обеспечивает как единый вход, так и SCIM provisioning.
Entra ID аутентифицируется, передавая Secret Token в заголовке Authorization: Bearer. Конечная точка SCIM ClickHouse Cloud ожидает, что значением bearer будут ключ и секрет токена, разделённые двоеточием.
Entra ID выполняет provisioning примерно каждые 40 минут. Чтобы немедленно обновить данные, используйте Provision on demand для нужного пользователя.
Откройте обращение в службу поддержки через ClickHouse Cloud консоль (Help → Contact support) и укажите:
  • идентификатор организации;
  • название и идентификатор объекта корпоративного приложения Entra ID;
  • снимок экрана с записью об ошибке из Provisioning → View provisioning logs.
Последнее изменение 14 августа 2026 г.