JWT authentication setup

How to configure per-service JWT (JWKS) authentication providers for a ClickHouse Cloud service from the console

This guide covers configuring JWKS providers in the Cloud console. To learn how to generate a JWT and what its structure looks like — its required claims, the roles and grants claims, and how ephemeral users work — see the JWT Authentication reference.

ClickHouse Cloud lets you authenticate connections to a service with JSON Web Tokens (JWTs) validated against your own JSON Web Key Set (JWKS) endpoints. Instead of managing database credentials, your identity provider issues short-lived tokens that ClickHouse verifies against the public keys published at a JWKS URL you configure.

You configure these JWKS providers yourself, per service, from Settings → Security in the ClickHouse Cloud console.

Before you begin

To configure JWT providers for a service, you need:

• An organization on the Enterprise plan.
• A service running ClickHouse version 26.4 or later.
• A role with the control-plane:service:manage permission on the service (for example, Admin or Service admin). Members without it see the section as read only.
• A publicly reachable HTTPS JWKS URL that publishes at least one RSA key (RS256) or, for services on version 26.8 or later, an EC key (ES256, ES384, ES512).

JWKS-based providers accept RSA keys and, from version 26.8, EC keys on the P-256, P-384, and P-521 curves. A JWKS document may contain other key types, but at least one usable key must be present.

How it works

The client (your identity provider or application) generates a JWT and signs it with its private key. The token must follow the expected token format. ClickHouse then verifies it against the public keys published at your JWKS URL:

1. ClickHouse reads the token’s kid (key ID) header and selects the matching key from your JWKS document.
2. It verifies the token signature against that public key and checks the iss (issuer) and aud (audience) claims against your provider configuration.
3. On success, the connection runs as an ephemeral user whose access rights come from the token’s clickhouse:grants and clickhouse:roles claims, capped by the permission limit (the default user). See Access rights for details.

ClickHouse validates and fetches the JWKS URL when you add or update a provider, so a misconfigured or unreachable URL is rejected up front.

Add a JWT provider

1. Open the service security settings

   Navigate to your service, open Settings, and scroll to the Security section. Find the JWT authentication card.

2. Open the providers flyout

   Select Set up JWT providers (or Manage JWT providers if you already have some). The flyout opens with a new provider form ready to fill in.

3. Fill in the provider details

   Complete the provider form and select Save.

   Field	Description
   Name	A unique name for this provider on the service. Cannot be changed after creation.
   Issuer	The expected iss claim of incoming tokens.
   Audience	The expected aud claim of incoming tokens.
   JWKS URL	The public HTTPS URL that publishes the public keys used to verify token signatures.
   Roles claim (optional)	The token claim to read ClickHouse roles from. Leave blank to use the default claim name clickhouse:roles. Roles named in the token must already exist on the service.

4. Add more providers if needed

   Use Add another provider to configure additional providers. A service can have at most five JWT providers.

Deleting a JWT provider immediately stops accepting tokens issued for it, and any workloads still authenticating with those tokens will stop working.

Limits

• A maximum of five JWT providers per service.
• JWKS providers accept RSA keys (RS256) and, from version 26.8, EC keys (ES256, ES384, ES512).
• The JWKS URL must be a public HTTPS endpoint. Private, internal, or link-local addresses are rejected.

Related

• JWT Authentication — token claims, ephemeral users, and client usage.