Skip to main content
本指南介绍如何在 Cloud 控制台中配置 JWKS 提供商。若要了解如何生成 JWT 及其结构，包括必需的声明、角色和授权声明，以及临时用户的工作方式，请参阅 JWT 身份验证参考文档。
ClickHouse Cloud 支持使用 JSON Web Token (JWT) 对服务连接进行身份验证，并根据您自己的 JSON Web Key Set (JWKS) 端点验证这些 JWT。您无需管理数据库凭据；身份提供商会签发短期有效的标记，ClickHouse 则会使用您配置的 JWKS URL 中发布的公钥对其进行验证。 您可以在 ClickHouse Cloud 控制台的 设置 → 安全 中，按服务自行配置这些 JWKS 提供商。

​
开始前准备

要为服务配置 JWT 提供商，您需要：
  • 一个使用 Enterprise 套餐的组织。
  • 一个运行 ClickHouse 26.4 或更高版本的服务。
  • 一个拥有该服务 control-plane:service:manage 权限的角色 (例如 Admin 或 Service admin) 。没有此权限的成员只能以只读方式查看此部分。
  • 一个可从公网访问的 HTTPS JWKS URL，并且该 URL 至少发布一个 RSA 密钥 (RS256)，或者对于 26.8 或更高版本的服务，发布一个 EC 密钥 (ES256、ES384、ES512) 。
基于 JWKS 的提供商接受 RSA 密钥，以及从 26.8 版本起接受 P-256、P-384 和 P-521 曲线上的 EC 密钥。JWKS 文档可以包含其他类型的密钥，但必须至少包含一个可用的密钥。

​
工作原理

客户端 (您的身份提供商或应用程序) 生成 JWT，并使用其私钥对其签名。标记必须符合预期的标记格式。随后，ClickHouse 会使用您 JWKS URL 上发布的公钥验证该标记：
  1. ClickHouse 读取标记 kid (密钥 ID) 请求头，并从您的 JWKS 文档中选择匹配的密钥。
  2. 它使用该公钥验证标记签名，并根据您的提供商配置检查 iss (签发方) 和 aud (受众) 声明。
  3. 验证成功后，连接将以临时用户身份运行；其访问权限来自标记中的 clickhouse:grants 和 clickhouse:roles 声明，并受权限上限 (default 用户) 约束。详见访问权限。
添加或更新提供商时，ClickHouse 会验证并拉取 JWKS URL，因此会预先拒绝配置错误或无法访问的 URL。

​
添加 JWT 提供商

1

打开服务安全设置

进入您的服务，打开设置，然后滚动到安全部分。找到 JWT 身份验证卡片。
2

打开提供商弹出面板

选择设置 JWT 提供商 (如果已有提供商，则选择管理 JWT 提供商) 。随即会打开弹出面板，其中显示可填写的新提供商表单。
3

填写提供商详细信息

填写提供商表单，然后选择保存。
4

按需添加更多提供商

使用添加另一个提供商配置更多提供商。每个服务最多可配置五个 JWT 提供商。
删除 JWT 提供商后，将立即不再接受为其签发的标记；任何仍使用这些标记进行身份验证的工作负载都将停止运行。

​
限制

  • 每个服务最多可配置 五个 JWT 提供商。
  • JWKS 提供商接受 RSA 密钥 (RS256) ，并从 26.8 版本起接受 EC 密钥 (ES256、ES384、ES512) 。
  • JWKS URL 必须是公网 HTTPS 端点。私网、内部或链路本地地址均会被拒绝。
最后修改于 2026年8月26日