CREATE USER ... IDENTIFIED WITH jwt не существует, и попытка выполнить его вызывает исключение. JWT-пользователи полностью управляются жизненным циклом токена.
Процесс аутентификации выглядит следующим образом:
- Клиент передаёт подписанный JWT одним из поддерживаемых способов (через HTTP-заголовок
Authorization: Bearer, TCP собственный протокол или поле gRPCjwt). - ClickHouse проверяет подпись токена.
- Проверяются обязательные утверждения (
exp,iat,iss,sub,aud). - В памяти создаётся эфемерный пользователь с правами доступа, сформированными на основе утверждений токена
clickhouse:grantsиclickhouse:rolesи ограниченными верхней границей разрешений. - Когда срок действия токена истекает, пользователя удаляет фоновая задача сборки мусора.
Утверждение
kid (идентификатор ключа) в заголовке также обязательно при использовании разрешения ключей на основе JWKS.
iss, sub и aud. Этот UUID остается стабильным при разных входах в систему. Пользователь, который входит в систему несколько раз с разными токенами (но с тем же издателем, subject и аудиторией), всегда получает один и тот же UUID.
Однако имя пользователя непостоянно. Оно формируется следующим образом:
<claims_hash> — это хеш, вычисляемый на основе утверждений iss, sub и aud вместе с утверждениями clickhouse:roles и clickhouse:grants. Утверждения iss и aud участвуют только через этот хеш; они больше не включаются напрямую в видимый префикс имени пользователя. Благодаря этому имя остается компактным и читаемым, когда iss/aud — это длинные непрозрачные URL IdP (например, Microsoft Entra или Okta), при этом по-прежнему гарантируется, что разные кортежи (iss, sub, aud) и разные наборы clickhouse:roles / clickhouse:grants сопоставляются разным стабильным именам. Утверждения, которые не участвуют в вычислении хеша (например, iat, exp, nbf или несвязанные пользовательские утверждения), не изменяют имя пользователя.
Часть <claims_hash> изменяется всякий раз, когда изменяются утверждения clickhouse:roles или clickhouse:grants. Это означает, что токены с разными наборами ролей или привилегий будут давать разные имена пользователей даже для одной и той же учетной записи.
Эффективные права доступа определяются следующим образом:
permission_limit — это набор прав доступа у эталонной роли или пользователя, заданных в качестве верхней границы. Права, запрашиваемые токеном сверх этого предела, отбрасываются без уведомления.
ClickHouse отслеживает утверждение iat (время выдачи) у последнего аутентифицированного токена для каждой стабильной идентичности. Если предъявляется токен, у которого iat совпадает с сохранённым значением или меньше него, server повторно использует существующего эфемерного пользователя без повторной проверки утверждений. Это не позволяет более старым токенам снижать разрешения пользователя.
Эфемерные пользователи создаются при первой успешной аутентификации токена и удаляются фоновой задачей сборки мусора после истечения valid_until (который вычисляется из exp). Интервал запуска GC задаётся параметром gc_interval (по умолчанию — 5 минут).
Между запусками GC пользователи с истёкшим сроком действия могут по-прежнему отображаться в system.users, но аутентифицироваться уже не смогут.
Поскольку UUID стабилен, вы можете назначать JWT-пользователю профили настроек, квоты, политики строк и политики маскирования столбцов с помощью SQL-команд. Эти назначения сохраняются в хранилище управления доступом (на диске или в ZooKeeper) и остаются в силе после истечения срока действия токена и повторной аутентификации.
Указывайте пользователя по его текущему имени:
Имя пользователя и UUID для заданной идентификационной сущности можно найти в столбцах
name и id таблицы system.users, пока пользователь активен.ALTER USER не работает напрямую с пользователями JWT, так как они доступны только в режиме только для чтения. Чтобы назначить профили настроек, квоты или политики, используйте команды ALTER SETTINGS PROFILE, ALTER QUOTA или ALTER ROW POLICY, как показано выше.
Когда эфемерный JWT-пользователь создаёт представление с
SQL SECURITY DEFINER, сервер автоматически создаёт постоянную теневую копию пользователя, которая выступает в качестве определителя представления. Этот теневой пользователь:
- Имеет имя
<original_jwt_username>:definer - Имеет
NO_AUTHENTICATION(не может использоваться для входа) - Сохраняет те же права доступа, что и исходный JWT-пользователь на момент создания представления
--jwt с clickhouse-client для аутентификации с помощью заранее полученного токена:
Флаг
--jwt нельзя использовать вместе с --user. Если указан --jwt, имя пользователя берётся из токена.Authorization как Bearer-токен:
Вход через OAuth2 с кодом устройства
clickhouse-client поддерживает интерактивную авторизацию OAuth 2.0 с кодом устройства (device authorization grant, RFC 8628) с помощью флага --login.
Для конечных точек ClickHouse Cloud, если не передан ни один параметр --oauth-*, клиент выполняет вход через IdP ClickHouse Cloud и автоматически обменивает токен (token exchange) на JWT, специфичный для ClickHouse. В течение сеанса токены обновляются прозрачно для пользователя. При получении нового токена клиент автоматически переподключается.
--oauth-url. Указание любого параметра --oauth-* включает сценарий входа через собственный IdP, в том числе для хостов ClickHouse Cloud (например, когда для сервиса включена JWT-аутентификация с собственным провайдером идентификации). Клиент определяет device_authorization_endpoint и token_endpoint по документу /.well-known/openid-configuration издателя (и связанным URL-адресам метаданных OAuth). Если присутствует поле grant_types_supported, оно должно содержать urn:ietf:params:oauth:grant-type:device_code. Если определить конечные точки не удаётся, клиент сообщает об ошибке; если метаданные недоступны, явно задайте оба параметра: --oauth-device-uri и --oauth-token-uri.
При входе клиент выводит короткий verification_uri и user_code (RFC 8628). Если IdP также возвращает verification_uri_complete, клиент выводит эту ссылку для быстрого перехода, открывает её в браузере и, при наличии утилиты qrencode, отображает её в терминале в виде QR-кода. Для IdP ClickHouse Cloud выводятся только verification_uri_complete и user_code. Конфиденциальные клиенты могут передать --oauth-client-secret вместе с --oauth-client-auth basic|post.
clickhouse:roles). Настройки приложения Entra ID, необходимые для этого сценария в ClickHouse Cloud, описаны в разделе JWT-аутентификация с Microsoft Entra ID.
У каждого сервиса ClickHouse Cloud есть предопределённый JWT-аутентификатор, который используется в SQL Console и в процессе входа clickhouse-client с параметром --login. Этот аутентификатор настроен следующим образом:
Для встроенного аутентификатора верхняя граница разрешений установлена на роль
default_role и пользователя default. Это означает, что итоговые права любого JWT-пользователя ограничиваются пересечением с привилегиями этих двух сущностей, поэтому токен никогда не сможет повысить привилегии сверх того, что разрешено default_role и default.
Чтобы использовать этот аутентификатор, ничего настраивать не нужно. Он создаётся автоматически при создании сервиса.
Включение JWT-аутентификации для сервиса
Помимо встроенного аутентификатора, вы можете настроить сервис ClickHouse Cloud для приема JWT, выданных вашим провайдером идентификации (например, Microsoft Entra или Okta). Эта возможность доступна в тарифе Enterprise для сервисов с ClickHouse версии 26.4 или более поздней. Вы можете настроить ее самостоятельно в консоли Cloud в разделе Настройки → Безопасность → JWT-аутентификация — пошаговые инструкции см. в разделе Настройка JWT-аутентификации, а полное описание настройки Entra ID — в разделе JWT-аутентификация с Microsoft Entra ID. Каждый провайдер определяется следующими параметрами:
Когда запрос перенаправляется на другой сегмент или реплику, JWT-токен передаётся в межсерверном протоколе. Удалённый узел повторно аутентифицирует токен независимо, создавая собственного эфемерного пользователя.
- Права доступа не предоставлены: У указанной роли или пользователя может не быть необходимых привилегий. Убедитесь, что роли, указанные в
clickhouse:roles, существуют и включают соответствующие привилегии. - Токен отклонён: Убедитесь, что
iss,audи алгоритм подписи в вашем токене соответствуют ожидаемым провайдером JWT. Если используется JWKS, убедитесь, чтоkidтокена соответствует ключу в наборе ключей провайдера. - Пользователь исчезает между запросами: Эфемерные пользователи удаляются после истечения срока действия токена. Для длительных сеансов используйте клиент, поддерживающий обновление токена (например, режим
--login). CREATE USER ... IDENTIFIED WITH jwtзавершается с ошибкой: Это ожидаемое поведение. Пользователей JWT нельзя создавать через DDL. Ими полностью управляет жизненный цикл токена.