> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# SCIM provisioning в Microsoft Entra ID
> Настройка SCIM provisioning между Microsoft Entra ID и ClickHouse Cloud
export const EnterprisePlanFeatureBadge = ({feature = 'Эта возможность', support = false, linking_verb_are = false}) => {
return
Возможность тарифа Enterprise
{feature} {linking_verb_are ? 'доступны' : 'доступна'} в тарифе Enterprise. {support ? `Чтобы включить эту возможность, обратитесь в службу поддержки.` : 'Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.'}
;
};
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](/docs/ru/products/cloud/guides/security/cloud-access-management/scim-setup). Настройка на стороне ClickHouse Cloud идентична; отличается только конфигурация IdP.
## Перед началом работы
Вам потребуется:
* Роль **Admin** в организации ClickHouse Cloud.
* Настроенная [SAML SSO](/docs/ru/products/cloud/guides/security/cloud-access-management/saml-sso-setup) между 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
Войдите в **ClickHouse Cloud консоль** как администратор организации и откройте **Настройки организации → Настройки SAML и SCIM → SCIM Configuration**.
Нажмите `Enable SCIM`. SCIM становится доступен после подключения SAML SSO. Если этот параметр неактивен, сначала завершите настройку SAML.
Будет сгенерирован **SCIM endpoint URL** следующего вида:
```plaintext theme={null}
https://api.clickhouse.cloud/v1/organizations//scim
```
Скопируйте его — позже вы вставите его в Entra ID в качестве **Tenant URL**.
Найдите раздел `Generate new key` и выберите дату истечения срока действия.
**Запланируйте ротацию**
Рекомендуем установить срок действия 12 месяцев и добавить напоминание в календарь. ClickHouse Cloud поддерживает до двух активных токенов SCIM одновременно, поэтому ротацию можно выполнить без простоя: создайте новый токен, переключите Entra ID на него, убедитесь, что подготовка пользователей по-прежнему работает, затем отзовите старый токен.
Нажмите `Generate new key`. Токен отображается **только один раз**: ключ с префиксом `scim_` и секрет. Сразу скопируйте оба значения и сохраните их в защищённом менеджере секретов — позднее получить их будет невозможно. Если вы их потеряете, отзовите токен и создайте новый.
Для Entra ID объедините ключ и секрет в один Bearer-токен следующего вида:
```plaintext theme={null}
:
```
То есть **ключ** токена, начинающийся с `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
Откройте страницу обзора **Microsoft Entra ID** и в разделе **Manage** левого меню выберите **Корпоративные приложения**. Откройте приложение, созданное при настройке SAML SSO для ClickHouse Cloud.
Если вы ещё не создали корпоративное приложение, сначала следуйте [руководству по настройке SAML SSO](/docs/ru/products/cloud/guides/security/cloud-access-management/saml-sso-setup#azure-enterprise-app) — при 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, объединенные двоеточием, в формате `:`. Entra ID отправляет их в заголовке `Authorization: Bearer`.
Нажмите `Test Connection`. Entra ID выполнит тестовый запрос к конечной точке SCIM; должно появиться уведомление об успешном выполнении. Если запрос завершится ошибкой, перейдите к разделу [Troubleshooting](#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.
**Используйте тот же адрес электронной почты, что и для SAML SSO**
Значение, передаваемое в `userName`, **должно** совпадать с адресом электронной почты, который каждый пользователь использует для входа через SAML SSO. SCIM создаёт аккаунт, а SAML аутентифицирует пользователя. Поэтому, если `userName` SCIM и адрес электронной почты в утверждении SAML не совпадают, SAML при входе создаст отдельного пользователя, которым SCIM не управляет, — появится дублирующий неуправляемый аккаунт. Сопоставьте `userName` с атрибутом (`userPrincipalName`, `mail` или другим), содержащим тот же адрес электронной почты, который передаёт ваша конфигурация SAML.
Остальные строки сопоставляются по умолчанию — убедитесь, что все они настроены:
| Атрибут 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.
**Регистр адресов электронной почты имеет значение**
Убедитесь, что значения, передаваемые в `userName` и основной адрес электронной почты, имеют одинаковый регистр. 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**
Для подготовки самих групп, а не только их участников, требуется Microsoft Entra ID P1 или выше. При подготовке групп сама группа создаётся в ClickHouse Cloud и связывается с соответствующей ролью по отображаемому имени.
**Назначьте пользователей.** Доступны два варианта:
* **Через группы (рекомендуется).** Добавьте пользователей в группы 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**, чтобы принудительно запустить синхронизацию, затем обратитесь к разделу [Устранение неполадок](#troubleshooting).
| # | Действие в 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 в 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. См. [Журнал аудита](/docs/ru/products/cloud/reference/security/audit-logging). Периодически проверяйте журнал, особенно после массового выделения ресурсов.
### Установите безопасную роль по умолчанию
Если пользователь 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_`), двоеточие и затем секрет. Не добавляйте пробелы в начале или конце и не указывайте префикс `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, указав значение в виде `:`. После обновления нажмите `Test Connection` для проверки. Когда подготовка снова будет выполняться без ошибок, отзовите старый токен в консоли ClickHouse Cloud.
Токены невозможно восстановить. В разделе **Organization settings → SAML and SCIM settings → SCIM Configuration** консоли ClickHouse Cloud отзовите утерянный токен и создайте новый, затем обновите **Secret Token** в Entra ID.
## Часто задаваемые вопросы
Да. SCIM создаёт учётные записи пользователей, а ClickHouse Cloud аутентифицирует их через SAML. Сначала настройте [SAML SSO](/docs/ru/products/cloud/guides/security/cloud-access-management/saml-sso-setup).
Да. При 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**.