Set up docs MCPJWT-аутентификация с пользовательским провайдером идентификации доступна в тарифе Enterprise. Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.
ClickHouse Cloud позволяет аутентифицировать подключения к сервису с помощью JSON Web Tokens (JWT), проверяемых по вашим конечным точкам JSON Web Key Set (JWKS). Вместо управления учетными данными базы данных ваш провайдер идентификации выпускает краткоживущие токены, которые ClickHouse проверяет по открытым ключам, опубликованным по указанному вами URL JWKS.
Вы можете самостоятельно настроить эти JWKS-провайдеры для каждого сервиса в разделе Settings → Security консоли ClickHouse Cloud.
Перед началом работы
Для настройки JWT-провайдеров для сервиса необходимы:
- Организация на тарифе Enterprise.
- Сервис, работающий под управлением ClickHouse версии 26.4 или более поздней.
- Роль с разрешением
control-plane:service:manageдля этого сервиса (например, Admin или Service admin). Участники без этого разрешения могут только просматривать данный раздел. - Общедоступный URL JWKS по протоколу HTTPS, публикующий хотя бы один ключ RSA (
RS256) или, для сервисов версии 26.8 или более поздней, ключ EC (ES256,ES384,ES512).
Как это работает
Клиент (ваш провайдер идентификации или приложение) создаёт JWT и подписывает его своим закрытым ключом. Токен должен соответствовать ожидаемому формату токена. Затем ClickHouse проверяет его с помощью открытых ключей, опубликованных по указанному вами URL JWKS:
- ClickHouse считывает из заголовка токена
kid(ID ключа) и выбирает соответствующий ключ из вашего документа JWKS. - Он проверяет подпись токена с помощью этого открытого ключа, а также сверяет утверждения
iss(издатель) иaud(аудитория) с конфигурацией вашего провайдера. - При успешной проверке соединение выполняется от имени эфемерного пользователя, чьи права доступа определяются утверждениями
clickhouse:grantsиclickhouse:rolesтокена и ограничены верхней границей разрешений (пользовательdefault). Подробнее см. в разделе Права доступа.
ClickHouse проверяет доступность URL JWKS и получает данные по нему при добавлении или обновлении провайдера, поэтому неверно настроенный или недоступный URL отклоняется сразу.
Добавление JWT-провайдера
Откройте настройки безопасности сервиса
Перейдите к сервису, откройте Settings и прокрутите страницу до раздела Security. Найдите карточку JWT-аутентификация.
Откройте выдвижную панель провайдеров
Выберите Set up JWT providers (или Manage JWT providers, если провайдеры уже настроены). Откроется выдвижная панель с готовой к заполнению формой нового провайдера.
Заполните сведения о провайдере
Заполните форму провайдера и нажмите Save.
| Поле | Описание |
|---|---|
| Name | Уникальное имя этого провайдера в сервисе. После создания его нельзя изменить. |
| Issuer | Ожидаемое значение утверждения iss во входящих токенах. |
| Audience | Ожидаемое значение утверждения aud во входящих токенах. |
| URL JWKS | Общедоступный HTTPS URL, по которому публикуются открытые ключи для проверки подписей токенов. |
| Roles claim (необязательно) | Утверждение токена, из которого считываются роли ClickHouse. Оставьте пустым, чтобы использовать имя утверждения по умолчанию clickhouse:roles. Роли, указанные в токене, должны уже существовать в сервисе. |
При необходимости добавьте других провайдеров
Используйте Add another provider, чтобы настроить дополнительные провайдеры. В сервисе может быть не более пяти JWT-провайдеров.
Ограничения
- Для каждого сервиса допускается не более пяти JWT-провайдеров.
- JWKS-провайдеры поддерживают ключи RSA (
RS256), а начиная с версии 26.8 — ключи EC (ES256,ES384,ES512). - URL JWKS должен быть общедоступной конечной точкой HTTPS. Частные, внутренние и локальные адреса канального уровня отклоняются.
- JWT-аутентификация — утверждения токена, эфемерные пользователи и использование клиентом.