JWT Authentication

ClickHouse can authenticate users using JSON Web Tokens (JWTs). Unlike other external authenticators such as LDAP or Kerberos, JWT authentication does not verify the identity of pre-existing users. Instead, it dynamically creates ephemeral users from the claims embedded in each token. These users exist only in memory, receive access rights derived from token claims, and are automatically removed after the token expires.

This makes JWT authentication fundamentally different from password-based or certificate-based methods: there is no CREATE USER ... IDENTIFIED WITH jwt statement, and attempting it raises an exception. JWT users are fully managed by the token lifecycle.

Overview

The authentication flow works as follows:

1. A client presents a signed JWT via one of the supported transport mechanisms (HTTP Authorization: Bearer header, the TCP native protocol, or the gRPC jwt field).
2. ClickHouse validates the token signature.
3. Required claims (exp, iat, iss, sub, aud) are verified.
4. An ephemeral user is created in memory with access rights derived from the clickhouse:grants and clickhouse:roles token claims, intersected with a permission limit.
5. When the token expires, a background garbage collection task removes the user.

Token claims

Required claims

Every JWT presented to ClickHouse must contain the following claims:

The kid (key ID) header claim is also required when JWKS-based key resolution is used.

Other recognized claims

Optional claims

Example token header and payload

{
  "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"]
}

Ephemeral user behavior

JWT users differ from regular ClickHouse users in several important ways.

Identity and naming

Each JWT user receives a deterministic UUID computed from the iss, sub, and aud claims. This UUID is stable across logins. A user who logs in multiple times with different tokens (but the same issuer, subject, and audience) always gets the same UUID.

The username, however, is volatile. It is constructed as:

JWT::<subject>::<claims_hash>

The <claims_hash> is a hash derived from the iss, sub, and aud claims together with the clickhouse:roles and clickhouse:grants claims. The iss and aud claims participate only through this hash; they are no longer inlined into the visible username prefix. This keeps the name compact and readable when iss/aud are long opaque IDP URLs (for example, Microsoft Entra or Okta), while still guaranteeing that distinct (iss, sub, aud) tuples and distinct clickhouse:roles / clickhouse:grants sets map to distinct, stable names. Claims that do not feed the hash (for example iat, exp, nbf, or unrelated custom claims) do not change the username.

The <claims_hash> portion changes whenever the clickhouse:roles or clickhouse:grants claims change. This means that tokens with different role or grant sets produce different usernames even for the same identity.

Access rights

Effective access rights are computed as:

effective_rights = permission_limit ∩ (token_grants ∪ token_roles)

Where permission_limit is the set of access rights held by a reference role or user configured as the upper bound. Rights requested by the token that exceed the limit are silently dropped.

Token freshness

ClickHouse tracks the iat (issued-at) claim of the most recently authenticated token for each stable identity. If a token with an iat equal to or older than the stored value is presented, the server reuses the existing ephemeral user without re-evaluating claims. This prevents older tokens from downgrading a user’s permissions.

Lifetime and garbage collection

Ephemeral users are created when a token is first authenticated and removed by a background garbage collection task after valid_until (derived from exp) passes. The GC interval is controlled by the gc_interval parameter (default: 5 minutes).

Between GC runs, expired users may still be visible in system.users but can no longer authenticate.

Persistent access assignments

Because the UUID is stable, you can assign settings profiles, quotas, row policies, and column masking policies to a JWT user using SQL statements. These assignments persist in the access control storage (on disk or in ZooKeeper) and survive token expiry and re-authentication.

Reference the user by their current username:

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

Note that ALTER USER does not work on JWT users directly, as they are read-only. To assign settings profiles, quotas, or policies, use the ALTER SETTINGS PROFILE, ALTER QUOTA, or ALTER ROW POLICY statements as shown above.

Differences from regular users

SQL SECURITY DEFINER views

When an ephemeral JWT user creates a view with SQL SECURITY DEFINER, the server automatically creates a persistent shadow copy of the user to serve as the view’s definer. This shadow user:

• Has the name <original_jwt_username>:definer
• Has NO_AUTHENTICATION (cannot be used to log in)
• Retains the same access rights as the original JWT user at the time the view was created

This ensures that the view continues to function after the ephemeral user’s token expires and the original user is garbage-collected.

Client usage

Passing a token directly

Use the --jwt flag with clickhouse-client to authenticate with a pre-obtained token:

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

HTTP interface

Send the token as a Bearer token in the Authorization header:

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

OAuth2 device code login

The clickhouse-client supports an interactive OAuth2 device code flow via the --login flag. For ClickHouse Cloud endpoints, the client automatically performs token exchange to obtain a ClickHouse-specific JWT. Tokens are refreshed transparently during the session. When a new token is obtained, the client reconnects automatically.

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

ClickHouse Cloud built-in JWT authenticator

Every ClickHouse Cloud service comes with a predefined JWT authenticator that is used by SQL Console and the clickhouse-client --login flow. This authenticator is configured with:

The built-in authenticator has a permission limit set to the default_role role and the default user. This means the effective rights of any JWT user are intersected with the grants held by those two entities, so a token can never escalate privileges beyond what default_role and default are allowed to do.

You do not need to configure anything to use this authenticator. It is provisioned automatically when the service is created.

Enabling JWT authentication for your service

In addition to the built-in authenticator, you can configure your ClickHouse Cloud service to accept JWTs issued by your own identity provider (for example, Microsoft Entra or Okta). This is a beta feature, available in the Enterprise plan for services running ClickHouse version 26.4 or later. You can configure it yourself from the Cloud console under Settings → Security → JWT authentication — see JWT authentication setup for step-by-step instructions. Each provider is defined by the following:

Interserver communication

When a query is forwarded to another shard or replica, the JWT token is included in the interserver protocol. The remote node re-authenticates the token independently, creating its own ephemeral user.

Troubleshooting

• No access rights granted: The referenced role or user may lack the required grants. Ensure the roles referenced in the clickhouse:roles exist and include the appropriate grants.
• Token rejected: Verify that iss, aud, and the signing algorithm in your token match what the JWT provider expects. If JWKS is used, ensure the token’s kid matches a key in the provider’s key set.
• User disappears between queries: Ephemeral users are removed after token expiry. Use a client that supports token refresh (e.g., --login mode) for long-running sessions.
• CREATE USER ... IDENTIFIED WITH jwt fails: This is expected. JWT users cannot be created via DDL. They are managed entirely by the token lifecycle.