Skip to main content
В этом руководстве описывается настройка JWKS-провайдеров в консоли Cloud. О том, как создать JWT, какова его структура, какие утверждения обязательны, что представляют собой утверждения ролей и привилегий, а также как работают эфемерные пользователи, см. в справочнике JWT-аутентификация.
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).
Провайдеры на основе JWKS поддерживают ключи RSA и, начиная с версии 26.8, ключи EC на кривых P-256, P-384 и P-521. Документ JWKS может содержать ключи других типов, но в нём должен присутствовать хотя бы один пригодный для использования ключ.

​
Как это работает

Клиент (ваш провайдер идентификации или приложение) создаёт JWT и подписывает его своим закрытым ключом. Токен должен соответствовать ожидаемому формату токена. Затем ClickHouse проверяет его с помощью открытых ключей, опубликованных по указанному вами URL JWKS:
  1. ClickHouse считывает из заголовка токена kid (ID ключа) и выбирает соответствующий ключ из вашего документа JWKS.
  2. Он проверяет подпись токена с помощью этого открытого ключа, а также сверяет утверждения iss (издатель) и aud (аудитория) с конфигурацией вашего провайдера.
  3. При успешной проверке соединение выполняется от имени эфемерного пользователя, чьи права доступа определяются утверждениями clickhouse:grants и clickhouse:roles токена и ограничены верхней границей разрешений (пользователь default). Подробнее см. в разделе Права доступа.
ClickHouse проверяет доступность URL JWKS и получает данные по нему при добавлении или обновлении провайдера, поэтому неверно настроенный или недоступный URL отклоняется сразу.

​
Добавление JWT-провайдера

1

Откройте настройки безопасности сервиса

Перейдите к сервису, откройте Settings и прокрутите страницу до раздела Security. Найдите карточку JWT-аутентификация.
2

Откройте выдвижную панель провайдеров

Выберите Set up JWT providers (или Manage JWT providers, если провайдеры уже настроены). Откроется выдвижная панель с готовой к заполнению формой нового провайдера.
3

Заполните сведения о провайдере

Заполните форму провайдера и нажмите Save.
4

При необходимости добавьте других провайдеров

Используйте Add another provider, чтобы настроить дополнительные провайдеры. В сервисе может быть не более пяти JWT-провайдеров.
При удалении JWT-провайдера токены, выданные для него, немедленно перестают приниматься, и все рабочие нагрузки, которые по-прежнему аутентифицируются с помощью этих токенов, перестанут работать.

​
Ограничения

  • Для каждого сервиса допускается не более пяти JWT-провайдеров.
  • JWKS-провайдеры поддерживают ключи RSA (RS256), а начиная с версии 26.8 — ключи EC (ES256, ES384, ES512).
  • URL JWKS должен быть общедоступной конечной точкой HTTPS. Частные, внутренние и локальные адреса канального уровня отклоняются.
  • JWT-аутентификация — утверждения токена, эфемерные пользователи и использование клиентом.
Последнее изменение 26 августа 2026 г.