Аутентификация JWT

ClickHouse может аутентифицировать пользователей с помощью JSON Web Tokens (JWT). В отличие от других внешних аутентификаторов, таких как LDAP или Kerberos, JWT-аутентификация не проверяет подлинность уже существующих пользователей. Вместо этого она динамически создаёт эфемерных пользователей на основе утверждений, встроенных в каждый токен. Эти пользователи существуют только в памяти, получают права доступа, определяемые утверждениями токена, и автоматически удаляются после истечения срока действия токена.

Это принципиально отличает JWT-аутентификацию от методов на основе паролей или сертификатов: оператора CREATE USER ... IDENTIFIED WITH jwt не существует, и попытка выполнить его вызывает исключение. JWT-пользователи полностью управляются жизненным циклом токена.

Процесс аутентификации выглядит следующим образом:

1. Клиент передаёт подписанный JWT одним из поддерживаемых способов (через HTTP-заголовок Authorization: Bearer, TCP собственный протокол или поле gRPC jwt).
2. ClickHouse проверяет подпись токена.
3. Проверяются обязательные утверждения (exp, iat, iss, sub, aud).
4. В памяти создаётся эфемерный пользователь с правами доступа, сформированными на основе утверждений токена clickhouse:grants и clickhouse:roles и ограниченными верхней границей разрешений.
5. Когда срок действия токена истекает, пользователя удаляет фоновая задача сборки мусора.

Каждый JWT, передаваемый в ClickHouse, должен содержать следующие утверждения:

Утверждение kid (идентификатор ключа) в заголовке также обязательно при использовании разрешения ключей на основе JWKS.

{
  "alg": "RS256",
  "kid": "my-key-id"
}

{
  "iss": "https://idp.example.com",
  "sub": "jane.doe",
  "aud": "my-clickhouse-cluster",
  "exp": 1719504000,
  "iat": 1719500400,
  "clickhouse:grants": ["SELECT ON analytics.*", "INSERT ON analytics.events"],
  "clickhouse:roles": ["analyst"]
}

Пользователи JWT отличаются от обычных пользователей ClickHouse по нескольким важным аспектам.

Каждый пользователь JWT получает детерминированный UUID, вычисляемый на основе утверждений iss, sub и aud. Этот UUID остается стабильным при разных входах в систему. Пользователь, который входит в систему несколько раз с разными токенами (но с тем же издателем, subject и аудиторией), всегда получает один и тот же UUID.

Однако имя пользователя непостоянно. Оно формируется следующим образом:

JWT::<subject>::<claims_hash>

Узел <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. Это означает, что токены с разными наборами ролей или привилегий будут давать разные имена пользователей даже для одной и той же учетной записи.

Эффективные права доступа определяются следующим образом:

effective_rights = permission_limit ∩ (token_grants ∪ token_roles)

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

ClickHouse отслеживает утверждение iat (время выдачи) у последнего аутентифицированного токена для каждой стабильной идентичности. Если предъявляется токен, у которого iat совпадает с сохранённым значением или меньше него, server повторно использует существующего эфемерного пользователя без повторной проверки утверждений. Это не позволяет более старым токенам снижать разрешения пользователя.

Эфемерные пользователи создаются при первой успешной аутентификации токена и удаляются фоновой задачей сборки мусора после истечения valid_until (который вычисляется из exp). Интервал запуска GC задаётся параметром gc_interval (по умолчанию — 5 минут).

Между запусками GC пользователи с истёкшим сроком действия могут по-прежнему отображаться в system.users, но аутентифицироваться уже не смогут.

Поскольку UUID стабилен, вы можете назначать JWT-пользователю профили настроек, квоты, политики строк и политики маскирования столбцов с помощью SQL-команд. Эти назначения сохраняются в хранилище управления доступом (на диске или в ZooKeeper) и остаются в силе после истечения срока действия токена и повторной аутентификации.

Указывайте пользователя по его текущему имени:

ALTER SETTINGS PROFILE my_profile ADD TO 'JWT::jane.doe::<claims_hash>';

Обратите внимание, что 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 для аутентификации с помощью заранее полученного токена:

clickhouse-client --host your-instance.clickhouse.cloud --secure --jwt '<your_jwt_token>'

Передайте токен в заголовке Authorization как Bearer-токен:

curl -H 'Authorization: Bearer <your_jwt_token>' \
    'https://your-instance.clickhouse.cloud:8443/?query=SELECT+currentUser()'

clickhouse-client поддерживает интерактивный OAuth2-поток Device Code через флаг --login. Для конечных точек ClickHouse Cloud клиент автоматически выполняет обмен токенов, чтобы получить JWT для ClickHouse. Токены прозрачно обновляются в течение сеанса. При получении нового токена клиент автоматически переподключается.

clickhouse-client --host your-instance.clickhouse.cloud --login

У каждого сервиса ClickHouse Cloud есть предопределённый JWT-аутентификатор, который используется в SQL Console и в процессе входа clickhouse-client с параметром --login. Этот аутентификатор настроен следующим образом:

Для встроенного аутентификатора верхняя граница разрешений установлена на роль default_role и пользователя default. Это означает, что итоговые права любого JWT-пользователя ограничиваются пересечением с привилегиями этих двух сущностей, поэтому токен никогда не сможет повысить привилегии сверх того, что разрешено default_role и default.

Чтобы использовать этот аутентификатор, ничего настраивать не нужно. Он создаётся автоматически при создании сервиса.

Помимо встроенного аутентификатора, вы можете настроить сервис ClickHouse Cloud для приема JWT, выданных вашим провайдером идентификации (например, Microsoft Entra или Okta). Это бета-возможность, доступная в тарифе Enterprise для сервисов с ClickHouse версии 26.4 или более поздней. Вы можете настроить ее самостоятельно в консоли Cloud в разделе Настройки → Безопасность → JWT-аутентификация — пошаговые инструкции см. в разделе Настройка JWT-аутентификации. Каждый провайдер определяется следующими параметрами:

Когда запрос перенаправляется на другой сегмент или реплику, JWT-токен передаётся в межсерверном протоколе. Удалённый узел повторно аутентифицирует токен независимо, создавая собственного эфемерного пользователя.

• Права доступа не предоставлены: У указанной роли или пользователя может не быть необходимых привилегий. Убедитесь, что роли, указанные в clickhouse:roles, существуют и включают соответствующие привилегии.
• Токен отклонён: Убедитесь, что iss, aud и алгоритм подписи в вашем токене соответствуют ожидаемым провайдером JWT. Если используется JWKS, убедитесь, что kid токена соответствует ключу в наборе ключей провайдера.
• Пользователь исчезает между запросами: Эфемерные пользователи удаляются после истечения срока действия токена. Для длительных сеансов используйте клиент, поддерживающий обновление токена (например, режим --login).
• CREATE USER ... IDENTIFIED WITH jwt завершается с ошибкой: Это ожидаемое поведение. Пользователей JWT нельзя создавать через DDL. Ими полностью управляет жизненный цикл токена.