Data

ClickHouse Cloud Adds JWT Authentication Support

ClickHouse Cloud now supports JWT authentication, allowing users to connect using short-lived tokens from an existing OpenID Connect provider instead of traditional database passwords.

AI-generated editorial illustration of the article topic; not a photograph, product screenshot or measured result.

Overview of JWT Authentication in ClickHouse Cloud

ClickHouse Cloud now supports JWT authentication, allowing users to connect using short-lived tokens from an existing OpenID Connect provider, such as Okta or Microsoft Entra, instead of traditional database passwords [ClickHouse]. This change, available in version 26.4 or later [ClickHouse], streamlines the authentication process by eliminating the need for separate database credentials. Identity and role management remain within the identity provider, while ClickHouse Cloud validates the JWT token for access [ClickHouse]. This approach enhances security by reducing the risk of password exposure and simplifies user management by leveraging existing identity infrastructure.

Implementation and Usage of JWT Tokens

Implementing JWT authentication in ClickHouse Cloud involves passing a valid JSON Web Token (JWT) to the client, which is then used to authenticate and authorize access to the database. When a valid token is received, ClickHouse creates an ephemeral user in memory and grants it the specific access rights defined in the token, such as roles like 'analyst' or 'reader' [ClickHouse]. This approach eliminates the need for traditional username and password authentication, streamlining the process for secure, role-based access.

Integration with various clients, such as clickhouse-js and clickhouse-connect, is straightforward, with the token provided via the access_token parameter [ClickHouse]. For ad hoc queries, tools like clickhouse-client and curl also support JWT authentication by passing the token directly as a command-line argument or HTTP header [ClickHouse]. Tokens have an expiration time, and clients typically support refresh logic to handle token renewal automatically.

Integration with Identity Providers and Token Management

Integration with Identity Providers and Token Management in ClickHouse Cloud allows clients to manage two distinct types of tokens: those issued by their own identity provider and those issued by ClickHouse Cloud for their Cloud account. Every Cloud service includes a built-in authenticator that issues tokens for your Cloud account. The SQL Console automatically uses these tokens, while the clickhouse-client --login command initiates an OAuth2 device code flow against your Cloud login. This process exchanges the result for a ClickHouse token, refreshes it in the background, and reconnects when a new token arrives. This approach ensures seamless and secure authentication without requiring manual intervention from the user.

Security and Governance Features

ClickHouse Cloud introduces JWT authentication as part of its broader security and governance work, enhancing access control and data protection. Row policies, such as those ensuring a regional team sees only its own region's rows, are integral to this approach. JWT-based access is managed through statements that reference the user's current name from the system.users table while they are active. For example, the statement ALTER SETTINGS PROFILE readonly_profile ADD TO 'JWT::jane.doe::' assigns permissions based on the JWT claims hash. These assignments are recorded in the same replicated access storage that holds roles and other SQL-created objects, backed by Keeper in ClickHouse Cloud. This ensures consistent and secure management of user access across the platform.

Availability and Setup Requirements

JWT authentication is now available in ClickHouse Cloud, offering a flexible and secure method for user authentication. This feature is supported across all enterprise plans and requires ClickHouse version 26.4 or higher (26.8 for EC keys). It integrates with built-in ClickHouse authenticators and custom identity providers, enabling use with SQL Console, clickhouse-client --login, and any client holding a token from an OIDC provider. Setup is straightforward, with options to configure through the cloud console under Settings → Security. JWT authentication relies on a signed statement that verifies a user's identity and roles, allowing for extensibility in what the token can carry and how it is used. For detailed information on claims, ephemeral users, and client usage, refer to the JWT authentication reference.