> ## 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 身份验证设置

> 如何通过控制台为 ClickHouse Cloud 服务配置服务级 JWT（JWKS）身份验证提供商

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Beta 版功能</span>
        </a>;
};

export const VersionBadge = ({minVersion}) => <div className="versionBadge">
    <div className="versionIcon" style={{
  marginRight: "8px",
  marginTop: "4px"
}}>
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path d="M5 14C5.82843 14 6.5 13.3284 6.5 12.5C6.5 11.6716 5.82843 11 5 11C4.17157 11 3.5 11.6716 3.5 12.5C3.5 13.3284 4.17157 14 5 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M5 5C5.82843 5 6.5 4.32843 6.5 3.5C6.5 2.67157 5.82843 2 5 2C4.17157 2 3.5 2.67157 3.5 3.5C3.5 4.32843 4.17157 5 5 5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M13 10.5C13.8284 10.5 14.5 9.82843 14.5 9C14.5 8.17157 13.8284 7.5 13 7.5C12.1716 7.5 11.5 8.17157 11.5 9C11.5 9.82843 12.1716 10.5 13 10.5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M11.5 9H9.5C9.03426 9 8.57493 8.89157 8.15836 8.68328C7.74179 8.475 7.37944 8.17259 7.1 7.8L5 5V11" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
      </svg>
    </div>
    自版本 {minVersion} 起可用
  </div>;

export const EnterprisePlanFeatureBadge = ({feature = '此功能', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Enterprise 计划功能
            </div>
            <div>
                <p>{feature} {linking_verb_are ? '可在' : '可在'} Enterprise 计划中使用。{support ? `请联系支持团队以启用此功能。` : '如需升级，请前往 Cloud Console 的套餐页面。'}</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

<BetaBadge />

<VersionBadge minVersion="26.4" />

<EnterprisePlanFeatureBadge feature="通过自定义身份提供商进行 JWT 身份验证" />

<Tip>
  本指南介绍如何在 Cloud 控制台中配置 JWKS 提供商。若要了解如何生成 JWT 及其结构，包括必需的声明、角色和授权声明，以及临时用户的工作方式，请参阅 [JWT 身份验证](/docs/zh/concepts/features/security/external-authenticators/jwt)参考文档。
</Tip>

ClickHouse Cloud 支持使用 JSON Web Token (JWT) 对服务连接进行身份验证，并根据您自己的 JSON Web Key Set (JWKS) 端点验证这些 JWT。您无需管理数据库凭据；身份提供商会签发短期有效的标记，ClickHouse 则会使用您配置的 JWKS URL 中发布的公钥对其进行验证。

您可以在 ClickHouse Cloud 控制台的 **设置 → 安全** 中，按服务自行配置这些 JWKS 提供商。

<div id="before-you-begin">
  ## 开始前准备
</div>

要为服务配置 JWT 提供商，您需要：

* 一个使用 **Enterprise** 套餐的组织。
* 一个运行 **ClickHouse 26.4 或更高版本**的服务。
* 一个拥有该服务 `control-plane:service:manage` 权限的角色 (例如 **Admin** 或 **Service admin**) 。没有此权限的成员只能以只读方式查看此部分。
* 一个可从公网访问的 **HTTPS** JWKS URL，并且该 URL 至少发布一个 **RSA** 密钥 (`RS256`)，或者对于 26.8 或更高版本的服务，发布一个 **EC** 密钥 (`ES256`、`ES384`、`ES512`) 。

<Note>
  基于 JWKS 的提供商接受 **RSA** 密钥，以及从 26.8 版本起接受 P-256、P-384 和 P-521 曲线上的 **EC** 密钥。JWKS 文档可以包含其他类型的密钥，但必须至少包含一个可用的密钥。
</Note>

<div id="how-it-works">
  ## 工作原理
</div>

客户端 (您的身份提供商或应用程序) 生成 JWT，并使用其**私钥**对其签名。标记必须符合预期的[标记格式](/docs/zh/concepts/features/security/external-authenticators/jwt#token-claims)。随后，ClickHouse 会使用您 JWKS URL 上发布的**公钥**验证该标记：

1. ClickHouse 读取标记 `kid` (密钥 ID) 请求头，并从您的 JWKS 文档中选择匹配的密钥。
2. 它使用该公钥验证标记签名，并根据您的提供商配置检查 `iss` (签发方) 和 `aud` (受众) 声明。
3. 验证成功后，连接将以临时用户身份运行；其访问权限来自标记中的 `clickhouse:grants` 和 `clickhouse:roles` 声明，并受权限上限 (`default` 用户) 约束。详见[访问权限](/docs/zh/concepts/features/security/external-authenticators/jwt#access-rights)。

添加或更新提供商时，ClickHouse 会验证并拉取 JWKS URL，因此会预先拒绝配置错误或无法访问的 URL。

<div id="add-a-jwt-provider">
  ## 添加 JWT 提供商
</div>

<Steps>
  <Step title="打开服务安全设置" id="open-security-settings">
    进入您的服务，打开**设置**，然后滚动到**安全**部分。找到 **JWT 身份验证**卡片。

    <Image img="https://mintcdn.com/private-7c7dfe99/-6hzQ2QWO_HW75mL/images/cloud/security/jwt/jwt-section.png?fit=max&auto=format&n=-6hzQ2QWO_HW75mL&q=85&s=79179b401f3a527316bffe67be424977" size="lg" alt="服务安全设置中的 JWT 身份验证部分" force width="1850" height="422" data-path="images/cloud/security/jwt/jwt-section.png" />
  </Step>

  <Step title="打开提供商弹出面板" id="open-flyout">
    选择**设置 JWT 提供商** (如果已有提供商，则选择**管理 JWT 提供商**) 。随即会打开弹出面板，其中显示可填写的新提供商表单。
  </Step>

  <Step title="填写提供商详细信息" id="fill-provider-details">
    填写提供商表单，然后选择**保存**。

    | 字段            | 描述                                                                           |
    | ------------- | ---------------------------------------------------------------------------- |
    | **名称**        | 此服务中该提供商的唯一名称。创建后无法更改。                                                       |
    | **签发方**       | 传入标记中预期的 `iss` 声明。                                                           |
    | **受众**        | 传入标记中预期的 `aud` 声明。                                                           |
    | **JWKS URL**  | 用于发布验证标记签名所需公钥的公开 HTTPS URL。                                                 |
    | **角色声明** (可选) | 用于从标记中读取 ClickHouse 角色的声明。留空以使用默认声明名称 `clickhouse:roles`。标记中指定的角色必须已存在于该服务中。 |
  </Step>

  <Step title="按需添加更多提供商" id="add-more-providers">
    使用**添加另一个提供商**配置更多提供商。每个服务最多可配置五个 JWT 提供商。
  </Step>
</Steps>

<Warning>
  删除 JWT 提供商后，将立即不再接受为其签发的标记；任何仍使用这些标记进行身份验证的工作负载都将停止运行。
</Warning>

<div id="limits">
  ## 限制
</div>

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

<div id="related">
  ## 相关内容
</div>

* [JWT 身份验证](/docs/zh/concepts/features/security/external-authenticators/jwt) — 标记声明、临时用户和客户端使用。