SCIM-провижининг с Okta

Как настроить SCIM-провижининг между Okta и ClickHouse Cloud

Поддержка SCIM-провижининга доступна в рамках закрытой предварительной версии.

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

В этом руководстве показано, как выполнить полную настройку SCIM-провижининга с Okta. Конечная точка SCIM в ClickHouse Cloud соответствует SCIM 2.0 (RFC 7644), но поддерживает только аутентификацию по Basic Auth, а Okta — единственный провайдер идентификации, с которым мы тестировали эту интеграцию. Другие IdP с поддержкой SCIM 2.0 тоже могут работать, если они поддерживают аутентификацию по Basic Auth, но на данный момент официально не поддерживаются.

​

Перед началом

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

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

​

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

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

​

Настройка SCIM для вашей организации ClickHouse Cloud

1. ​

   Включите SCIM

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

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

   Будет сгенерирован URL конечной точки SCIM в формате:

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

   Скопируйте его — позже вы вставите этот URL в Okta.

2. ​

   Сгенерируйте токен доступа SCIM

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

   Запланируйте ротацию. Рекомендуем установить срок действия 12 месяцев и добавить напоминание в календарь. ClickHouse Cloud поддерживает до двух активных токенов SCIM одновременно, поэтому ротацию можно выполнить без простоя: сгенерируйте новый токен, переключите на него Okta, убедитесь, что провижининг по-прежнему работает, затем отзовите старый токен.

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

3. ​

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

   В панели SCIM Configuration нажмите Map roles in “Users and roles” (или перейдите напрямую через Users and roles → Roles).

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

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

​

Настройка приложения ClickHouse Cloud в Okta

1. ​

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

   В консоли администратора Okta перейдите в Applications → Applications и найдите приложение, которое вы создали при настройке SAML SSO для ClickHouse Cloud. Откройте его.

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

   На вкладке General найдите раздел App Settings и нажмите Edit. В разделе Provisioning выберите SCIM, затем нажмите Save.

   Теперь в приложении отображается вкладка Provisioning.

2. ​

   Подключите Okta к конечной точке SCIM

   Откройте вкладку Provisioning приложения и нажмите Edit. Заполните форму:

   • SCIM connector base URL — URL конечной точки SCIM, который вы получили ранее.
   • Unique identifier field for users — userName.
   • Supported provisioning actions — выберите все перечисленные ниже пункты:
     • Import New Users and Profile Updates
     • Push New Users
     • Push Profile Updates
     • Push Groups
     • Import Groups
   • Authentication Mode — Basic Auth.
     • Username — ключ токена SCIM (начинается с scim_).
     • Password — секрет токена SCIM.

   Нажмите Test Connector Configuration. Вы должны увидеть зеленое подтверждение. Если проверка не пройдет, перейдите к разделу Troubleshooting.

   Нажмите Save.

3. ​

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

   Находясь на вкладке Provisioning, нажмите To App на левой боковой панели. Нажмите Edit и включите:

   Параметр	Действие	Что делает
   Создание пользователей	Включить	Создаёт новых пользователей в ClickHouse Cloud при назначении в Okta
   Обновление атрибутов пользователя	Включить	Автоматически передаёт изменения профиля (имя, email и т. д.)
   Деактивация пользователей	Включить	Удаляет пользователя из ClickHouse Cloud при снятии назначения или деактивации в Okta
   Синхронизация пароля	Отключить	Не используется — вход выполняется через SAML, а не по паролю

   Нажмите Save, затем вернитесь на вкладки Sign On / Provisioning приложения, чтобы убедиться, что настройки сохранены.

4. ​

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

   Okta и ClickHouse Cloud должны одинаково сопоставлять пользовательские поля. На вкладке Provisioning нажмите To App и проверьте Attribute Mappings для вашего приложения. Значения по умолчанию в приложении Okta SAML обычно подходят — сверьтесь с таблицей ниже:

   Атрибут Okta	Атрибут ClickHouse Cloud (SCIM)	Обязательно
   userName	userName	Да — используется как уникальный идентификатор и основной адрес электронной почты
   email (primary)	emails[primary].value	Да — должен совпадать с userName
   firstName	name.givenName	Рекомендуется
   lastName	name.familyName	Рекомендуется
   displayName	displayName	Рекомендуется — отображается в интерфейсе ClickHouse Cloud
   externalId	externalId	Рекомендуется — повышает точность при сопоставлении

   Вы можете добавить необязательные атрибуты, такие как department, manager и location — ClickHouse Cloud сохраняет их в профиле пользователя, но пока не использует для разрешений. Всё, что выходит за рамки стандартного набора SCIM, на стороне ClickHouse Cloud игнорируется.

   Регистр в email важен. Убедитесь, что userName и email в Okta используют одинаковый регистр. ClickHouse Cloud приводит email к нижнему регистру; расхождения между этими двумя полями могут вызывать сбои при тестировании.

5. ​

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

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

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

   Откройте только что созданную группу и нажмите Assign people, чтобы добавить в нее пользователя.

   Затем назначьте приложение SCIM той же группе, чтобы назначение ролей и доступ к приложению оставались синхронизированы.

   Отправьте группы. На вкладке Provisioning приложения нажмите Push Groups → Find groups by name, найдите нужную группу и нажмите Save. Повторите это для каждой ролевой группы. После Provisioning у каждой из них должен отображаться Push Status со значением Active (Pushed).

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

   • Через группы (рекомендуется). Добавьте пользователей в группы Okta, которые вы только что отправили. Они будут автоматически добавлены в ClickHouse Cloud и получат соответствующую роль.
   • Напрямую. На вкладке Assignments приложения нажмите Assign → Assign to People и выберите отдельных пользователей. Им будет назначена роль Default role, если только они также не входят в отправленную группу.

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

​

Протестируйте интеграцию

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

Выполните эту короткую проверку с одним или двумя тестовыми пользователями до назначения всей команды. Каждый шаг должен выполняться в течение нескольких секунд; если это не так, проверьте очередь задач Okta и раздел Устранение неполадок.

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

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

Где искать ошибки SCIM в Okta. Ошибки SCIM отображаются в Reports → System Log, отфильтрованном по вашему приложению, а также на экране Provisioning → View Logs приложения. Сообщение об ошибке, возвращаемое ClickHouse Cloud, показывается дословно — начните с него.

​

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

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

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

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

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

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

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

​

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

​

Сбой при выполнении команды “Проверить конфигурацию коннектора” в Okta

• Убедитесь, что SCIM включен в консоли ClickHouse Cloud.
• Убедитесь, что базовый URL в Okta в точности совпадает с URL конечной точки SCIM, показанным в консоли Cloud, — идентификатор организации должен быть указан верно.
• Убедитесь, что ключ токена и секрет вставлены без пробелов в начале и конце.
• Если вы ротировали токены, убедитесь, что используете новый ключ и секрет, а не предыдущую пару.

​

Пользователи создаются, но не получают разрешений

• Проверьте, что в разделе Сопоставление ролей в “Users and roles” добавлена строка для нужной роли.
• Проверьте, что имя группы Okta точно совпадает с именем группы SCIM в сопоставлении, включая регистр и дефисы.
• Если в вашей конфигурации часть пользователей намеренно создаётся без группы, убедитесь, что задана Роль по умолчанию.

​

Дубликат пользователя в списке участников

Обычно это происходит из-за различий в регистре адреса электронной почты в Okta и в более раннем приглашении, отправленном вручную. Удалите дубликат из списка участников, затем снимите назначение пользователя в Okta и назначьте его заново, чтобы повторно создать учетную запись.

​

Ошибка при отправке группы: “displayName not recognised”

Имя группы в Okta не совпадает с настроенным сопоставлением в ClickHouse Cloud. Переименуйте группу в Okta или добавьте сопоставление в разделе Сопоставить роли в “Users and roles” на панели конфигурации SCIM (или через Users and roles → Roles).

​

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

На распространение информации о деактивации в Okta может уйти до минуты. Если через несколько минут пользователь всё ещё числится участником, проверьте в Okta раздел Provisioning → View Logs на наличие ошибки в задаче деактивации.

​

Я сменил токен SCIM, и теперь Okta не работает

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

​

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

Токены нельзя восстановить. В настройках организации → настройках SAML и SCIM → SCIM Configuration в консоли ClickHouse Cloud отзовите утерянный токен и сгенерируйте новый, а затем обновите учетные данные в Okta.

​

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

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

Работает ли SCIM с Microsoft Entra ID, OneLogin или другими SCIM 2.0 IdP? Официально нет — на данный момент мы тестировали и поддерживаем только Okta. Конечная точка соответствует SCIM 2.0 (RFC 7644), но аутентификация ограничена Basic Auth, поэтому любой IdP, который не поддерживает аутентификацию через Basic Auth, работать не будет. Другие SCIM 2.0 IdP с поддержкой Basic Auth могут работать на практике, но мы этого не гарантируем.

Как быстро изменения в Okta появляются в ClickHouse Cloud? Большинство операций применяется в течение нескольких секунд. Массовые изменения (крупная push-операция для группы) могут занимать больше времени в зависимости от объёма, но Okta автоматически выполняет повторные попытки при временных ошибках.

Можно ли подключить несколько организаций ClickHouse Cloud к одному тенанту Okta? Да — установите приложение отдельно для каждой организации, с собственными URL конечной точки SCIM и токеном. При необходимости отправляйте одни и те же группы Okta в каждое приложение.

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

• идентификатор вашей организации,
• идентификатор вашего приложения Okta и
• скриншот неудачной задачи или теста из журналов Okta.