Skip to main content
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. Once the feature is enabled for your organization, you configure these JWKS providers yourself, per service, from Settings → Security in the ClickHouse Cloud console.
To enable JWT providers for your organization, reach out to support.

​
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 (tokens must be signed with RS256).
JWKS-based providers accept RSA keys only. Tokens signed with HMAC (HS256) or EC (ES256) keys cannot be verified against a JWKS endpoint and are rejected. A JWKS document may contain other key types, but at least one usable RSA 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 RSA 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.
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 / RS256 keys only.
  • The JWKS URL must be a public HTTPS endpoint. Private, internal, or link-local addresses are rejected.
Last modified on August 20, 2026