Перед началом работы
Вам потребуется:- Организация на тарифном плане Enterprise и сервис с ClickHouse версии 26.4 или новее.
-
Роль ClickHouse Cloud с разрешением
control-plane:service:manageдля сервиса (например, Администратор или Администратор сервиса), чтобы добавить провайдер JWT. - Доступ к Microsoft Entra admin center с ролью не ниже Cloud Application Administrator.
- Microsoft Entra ID P1 или P2, если вы хотите назначать ролям приложения группы, а не отдельных пользователей.
-
Azure CLI (
az) иclickhouse-clientдля проверки настройки. -
Список ролей ClickHouse, которые вы хотите выдавать через Entra ID. Каждая из них станет ролью приложения Entra ID с тем же именем. В этом руководстве используются две роли:
Как это работает
- Вы регистрируете в Entra ID приложение, представляющее ваш сервис ClickHouse Cloud, и определяете по одной роли приложения для каждой роли ClickHouse.
- Вы назначаете этим ролям приложения пользователей, группы и приложения Entra ID.
- Пользователь входит в систему через Azure CLI или
clickhouse-client --login, либо приложение использует поток client credentials grant (предоставление учётных данных клиента). Entra ID выдаёт токен доступа версии 2.0, в котором утверждениеaudсодержит идентификатор приложения (клиента), а утверждениеroles— список ролей приложения, назначенных вызывающей стороне. - ClickHouse Cloud проверяет подпись токена по открытым ключам Entra ID, проверяет утверждения
issиaudи создаёт эфемерного пользователя с привилегиями ролей ClickHouse, перечисленных в утвержденииroles. При этом привилегии такого пользователя не могут превышать привилегии пользователяdefault.
Регистрация ClickHouse в Entra ID
Зарегистрируйте приложение
- Name: отображаемое имя, например
clickhouse-cloud-production. - Supported account types: один тенант. В зависимости от версии портала этот вариант называется Single tenant only или Accounts in this organizational directory only.
- Redirect URI: оставьте пустым. Пользователи входят в систему через device code flow, в котором URI перенаправления не используется.
- Application (client) ID — далее
<CLIENT_ID>. Это значение становится утверждениемaudв токенах. - Directory (tenant) ID — далее
<TENANT_ID>. Это значение входит в состав издателя и URL набора JWKS.
Запросите токены доступа v2.0
https://sts.windows.net/<TENANT_ID>/. Вместо этого настройте приложение на получение токенов версии v2.0: их издатель — https://login.microsoftonline.com/<TENANT_ID>/v2.0, а утверждение aud всегда содержит идентификатор клиента (client ID).В регистрации приложения откройте раздел Manifest, укажите версию токена доступа 2 и нажмите Save. Имя свойства зависит от формата манифеста, отображаемого в редакторе:- Формат Microsoft Graph:
requestedAccessTokenVersionв разделеapi. - Формат Azure AD Graph:
accessTokenAcceptedVersionна верхнем уровне, как показано на снимке экрана ниже.
Предоставление API
-
Рядом с Application ID URI нажмите Add, оставьте значение по умолчанию
api://<CLIENT_ID>и сохраните изменения. Клиенты используют этот URI для запроса токенов к ClickHouse. Он не влияет на утверждениеaudв токенах v2.0 — в нём по-прежнему указывается ID клиента. -
Нажмите Add a scope и заполните форму. Пользователи запрашивают эту область при входе в систему. Приложения, которые проходят аутентификацию от собственного имени, её не используют.
Создайте роли приложения
roles токена, поэтому оно должно в точности совпадать с именем роли ClickHouse, включая регистр.Откройте App roles и для каждой роли ClickHouse выберите Create app role:Требовать назначения
Назначьте пользователям и группам роли приложения
roles он получает их все.Создание соответствующих ролей в ClickHouse
Подключитесь к сервису от имени пользователяdefault (например, через консоль SQL) и создайте роль для каждого значения роли приложения:
- Имена ролей чувствительны к регистру и должны совпадать со значениями ролей приложения.
- ClickHouse игнорирует имена в утверждении
roles, которым не соответствует ни одна существующая роль в сервисе. - Верхней границей разрешений для провайдеров JWT в ClickHouse Cloud служит пользователь
default. ClickHouse отбрасывает все привилегии роли, которых нет у пользователяdefault.
Добавление Entra ID в качестве провайдера JWT
Выполните шаги из раздела Добавление провайдера JWT и укажите следующие значения:Подключение от имени пользователя
Задайте значения из регистрации приложения и имя хоста сервиса в качестве переменных командной оболочки:Передача токена Azure CLI
Войдите в Azure CLI, запросите токен доступа для приложения ClickHouse и передайте его вclickhouse-client через параметр --jwt:
--login.
Вход с помощью clickhouse-client
clickhouse-client может самостоятельно выполнять авторизацию по OAuth 2.0 device code flow и обновлять токен в течение сеанса:
offline_access из области видимости: благодаря этому Entra ID возвращает токен обновления, с помощью которого клиент обновляет токен доступа. Без него после истечения срока действия токена доступа придётся входить заново.
Подключение от имени приложения
Приложения, такие как ETL-задания и серверные сервисы, проходят аутентификацию от собственного имени с помощью OAuth 2.0 client credentials grant. Роли приложения, назначаемые приложению, должны допускать тип участника Applications.- В разделе App registrations зарегистрируйте отдельное приложение для рабочей нагрузки. В разделе Certificates & secrets создайте секрет клиента или загрузите сертификат. В приведённых ниже командах идентификатор клиента и секрет рабочей нагрузки обозначены как
<WORKLOAD_CLIENT_ID>и<WORKLOAD_CLIENT_SECRET>. - В регистрации приложения рабочей нагрузки откройте API permissions и выберите Add a permission. В разделе APIs my organization uses найдите приложение ClickHouse, выберите Application permissions, отметьте роли приложения, необходимые рабочей нагрузке, и нажмите Add permissions.
- Нажмите Grant admin consent, чтобы назначить роли приложения рабочей нагрузке.
Проверка
После подключения проверьте идентичность и привилегии текущего сеанса:default и назначает полученный результат непосредственно пользователю. Именно поэтому SHOW CURRENT ROLES не возвращает ни одной строки.
Для пользовательских токенов Entra ID записывает в sub непрозрачный идентификатор, уникальный для каждой пары «пользователь — приложение». Это не адрес электронной почты пользователя и не его object ID.
Рекомендуемые практики
Назначайте группы, а не отдельных пользователей
Назначьте каждой роли приложения одну группу Entra ID, а затем предоставляйте или отзывайте доступ, меняя состав участников группы. Тогда при приходе сотрудников в команду или их уходе никому не придётся вносить изменения в приложение.Используйте отдельную регистрацию приложения для каждого окружения
В утвержденииaud токены содержат идентификатор клиента (client ID) регистрации приложения, для которой они выданы. Если для продакшн- и staging-окружения используются отдельные регистрации приложений, токен, выданный для одного окружения, не позволит пройти аутентификацию в другом.
Изменения ролей вступают в силу только с новым токеном
Entra ID записывает утверждениеroles в момент выдачи токена. Поэтому после изменения назначений ролей приложения для пользователя изменения вступят в силу, только когда пользователь получит новый токен. Уже выданные токены сохраняют прежние роли до истечения срока их действия. Чтобы сразу получить новый токен в Azure CLI, выполните az logout и az login.
Устранение неполадок
Токен отклоняется, а его издатель начинается с https://sts.windows.net
Токен отклоняется, а его издатель начинается с https://sts.windows.net
requestedAccessTokenVersion значение 2 в манифесте приложения, как описано в разделе Запрос токенов доступа v2.0, и запросите новый токен.Токен отклоняется из-за аудитории
Токен отклоняется из-за аудитории
- Значением Audience провайдера в ClickHouse Cloud должен быть идентификатор клиента, а не
api://<CLIENT_ID>. - Убедитесь, что вы запросили токен именно для приложения ClickHouse. Без
--resourceкомандаaz account get-access-tokenвернёт токен для Azure Resource Manager.
Entra ID возвращает AADSTS65001 или запрашивает согласие
Entra ID возвращает AADSTS65001 или запрашивает согласие
access_as_application. Добавьте его идентификатор клиента в разделе Expose an API → Authorized client applications, как описано в разделе Авторизация клиентского приложения для входа пользователей.Entra ID возвращает AADSTS50105 или AADSTS501051
Entra ID возвращает AADSTS50105 или AADSTS501051
Аутентификация проходит успешно, но запросы завершаются ошибкой ACCESS_DENIED
Аутентификация проходит успешно, но запросы завершаются ошибкой ACCESS_DENIED
- Для параметра Roles claim провайдера задано значение
roles. - Токен содержит утверждение
roles. Оно отсутствует, если вызывающая сторона назначена приложению без роли приложения. - Каждое значение в утверждении
rolesсовпадает с одной из существующих ролей ClickHouse в сервисе, включая регистр. - У пользователя
defaultесть привилегии, которые вы выдаёте роли.
Токен отклоняется после настройки политики сопоставления утверждений
Токен отклоняется после настройки политики сопоставления утверждений
https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys?appid=<CLIENT_ID>.См. также
- Настройка JWT-аутентификации: добавление, изменение и удаление провайдеров JWT в консоли Cloud.
- JWT-аутентификация: утверждения токенов, эфемерные пользователи и использование в клиентах.