> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# JWT authentication setup
> How to configure per-service JWT (JWKS) authentication providers for a ClickHouse Cloud service from the console
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return Beta;
}
return Beta feature;
};
export const VersionBadge = ({minVersion}) =>
{feature} {linking_verb_are ? 'are' : 'is'} available in the Enterprise plan. {support ? `Contact support to enable this feature.` : 'To upgrade, visit the plans page in the cloud 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](/docs/operations/external-authenticators/jwt) 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](https://clickhouse.com/support/program).
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](/docs/operations/external-authenticators/jwt#token-claims). 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](/docs/operations/external-authenticators/jwt#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
Navigate to your service, open **Settings**, and scroll to the **Security** section. Find the **JWT authentication** card.
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.
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 your RSA 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. |
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.