开始之前
您需要准备:- 一个使用 Enterprise 套餐的组织,以及一个运行 ClickHouse 26.4 或更高版本 的服务。
-
一个在该服务上拥有
control-plane:service:manage权限的 ClickHouse Cloud 角色 (例如 管理员 或 服务管理员) ,用于添加 JWT 提供商。 - Microsoft Entra admin center 的访问权限,且至少具有 Cloud Application Administrator 角色。
- 如果希望将组 (而非单个用户) 分配给应用角色,则需要 Microsoft Entra ID P1 或 P2。
-
Azure CLI (
az) 和clickhouse-client,用于测试配置。 -
一份计划通过 Entra ID 授予的 ClickHouse 角色列表。每个角色都会对应一个同名的 Entra ID 应用角色。本指南使用以下两个角色:
工作原理
- 在 Entra ID 中注册一个代表 ClickHouse Cloud 服务的应用程序,并为每个 ClickHouse 角色分别定义一个应用角色。
- 将 Entra ID 用户、组和应用程序分配给这些应用角色。
- 用户通过 Azure CLI 或
clickhouse-client --login登录,或由应用程序通过客户端凭证授权流程进行身份验证。随后,Entra ID 签发 v2.0 访问令牌:其aud声明为应用程序 (客户端) ID,roles声明则列出分配给调用方的应用角色。 - ClickHouse Cloud 使用 Entra ID 公钥验证令牌签名,检查
iss和aud声明,然后创建一个临时用户。该用户拥有roles声明中所列 ClickHouse 角色的特权,但不会超出default用户的特权范围。
在 Entra ID 中注册 ClickHouse
1
创建应用注册
在 Microsoft Entra 管理中心中,打开 App registrations,然后选择 New registration:
- Name:显示名称,例如
clickhouse-cloud-production。 - Supported account types:单租户。根据门户版本不同,此选项显示为 Single tenant only 或 Accounts in this organizational directory only。
- Redirect URI:留空。用户通过设备代码流登录,该流程无需重定向 URI。
- Application (client) ID,下文称为
<CLIENT_ID>。该值将作为令牌的aud声明。 - Directory (tenant) ID,下文称为
<TENANT_ID>。该值是签发方和 JWKS URL 的组成部分。
2
申请 v2.0 访问令牌
默认情况下,Entra ID 签发的是 v1.0 访问令牌,其签发方为
https://sts.windows.net/<TENANT_ID>/。请将应用程序改为接收 v2.0 令牌:其签发方为 https://login.microsoftonline.com/<TENANT_ID>/v2.0,且 aud 声明始终为客户端 ID。在应用注册中打开 Manifest,将访问令牌版本设置为 2,然后选择 保存。具体的属性名称取决于编辑器所显示的清单格式:- Microsoft Graph 格式:
api部分中的requestedAccessTokenVersion。 - Azure AD Graph 格式:顶层的
accessTokenAcceptedVersion,如下方截图所示。
3
公开 API
打开 Expose an API:
-
在 Application ID URI 旁边,选择 Add,接受默认值
api://<CLIENT_ID>并保存。客户端通过此 URI 请求用于访问 ClickHouse 的令牌。此操作不会更改 v2.0 令牌的aud声明,其值仍为客户端 ID。 -
选择 Add a scope 并填写表单。用户登录时会请求此作用域,而以自身身份进行认证的应用程序则不会使用它。
5
创建应用角色
每个应用角色对应一个 ClickHouse 角色。应用角色的 Value 就是令牌
roles 声明中出现的值,必须与 ClickHouse 角色名称完全一致 (包括大小写) 。打开 App roles,为每个 ClickHouse 角色选择 Create app role:以下示例定义了三个应用角色,其值均为 ClickHouse 角色名称:
6
需要分配
默认情况下,tenant 中的任何用户都可以获取该应用程序的令牌。如需仅允许已分配到应用角色的用户、组和应用程序获取令牌,请打开 Enterprise applications,选择与应用注册同名的应用程序,打开 Properties,将 Assignment required? 设置为 Yes,然后选择 Save。
7
将用户和组分配给应用角色
在同一个企业应用程序中,打开 Users and groups,然后选择 Add user/group。选择用户或组,再选择应用角色,然后选择 Assign。对每个用户或组重复上述操作。如果某个用户被直接分配或通过组分配了多个应用角色,
roles 声明中会包含所有这些角色。将组分配给应用角色需要 Microsoft Entra ID P1 或 P2。不支持嵌套组:只有已分配组的直接成员才会获得该组的应用角色。
在 ClickHouse 中创建对应的角色
以default 用户身份连接到您的服务 (例如通过 SQL 控制台) ,然后为每个应用角色值分别创建一个角色:
- 角色名称区分大小写,且必须与应用角色的值完全一致。
- 如果
roles声明中的名称与该服务上的任何现有角色都不匹配,ClickHouse 会忽略这些名称。 - 在 ClickHouse Cloud 中,JWT 提供商的权限上限为
default用户。如果某个角色拥有default用户所不具备的特权,ClickHouse 会删除这些特权。
将 Entra ID 添加为 JWT 提供商
按照添加 JWT 提供商中的步骤操作,并填写以下值:以用户身份连接
将应用注册中的各项值以及服务主机名设置为 shell 变量:传递 Azure CLI 令牌
使用 Azure CLI 登录,为 ClickHouse 应用程序申请访问令牌,然后通过--jwt 参数将其传递给 clickhouse-client:
--login。
使用 ClickHouse 客户端登录
clickhouse-client 可以自行完成 OAuth 2.0 设备授权码流程,并在会话期间自动续期令牌:
offline_access:这样 Entra ID 会返回 refresh token,客户端可借此续期访问令牌。如果不保留,访问令牌过期后您就必须重新登录。
以应用程序身份连接
ETL 作业、后端服务等应用程序使用 OAuth 2.0 客户端凭证授权流程,以自身身份进行身份验证。授予应用程序的应用角色必须允许 Applications 成员类型。- 在 App registrations 中,为该工作负载单独注册一个应用程序。在 Certificates & secrets 下,创建客户端密码或上传证书。以下命令中,该工作负载的客户端 ID 和密码分别用
<WORKLOAD_CLIENT_ID>和<WORKLOAD_CLIENT_SECRET>表示。 - 在该工作负载的应用注册中,打开 API permissions,然后选择 Add a permission。在 APIs my organization uses 下找到 ClickHouse 应用程序,选择 Application permissions,勾选该工作负载所需的应用角色,然后选择 Add permissions。
- 选择 Grant admin consent,将应用角色分配给该工作负载。
验证
连接成功后,检查当前会话的身份和特权:
ClickHouse 不会将这些角色本身授予临时用户,而是收集令牌中所列角色的特权,与
default 用户的特权求交集,再将结果直接授予该用户。因此,SHOW CURRENT ROLES 不会返回任何行。
对于用户令牌,Entra ID 会将 sub 设置为一个不透明标识符,该标识符对每个用户与应用程序的组合都是唯一的。它既不是用户的电子邮件地址,也不是其对象 ID。
最佳实践
分配组,而非单个用户
为每个应用角色分配一个 Entra ID 组,然后通过调整组成员来授予或撤销访问权限。这样,人员加入或离开团队时,无需任何人修改应用程序。为每个环境使用单独的应用注册
令牌的aud 声明中携带其所属应用注册的客户端 ID。如果为生产环境和预发布环境分别使用独立的应用注册,那么为其中一个环境签发的令牌就无法在另一个环境中通过身份验证。
角色变更将在下一个令牌中生效
Entra ID 会在签发令牌时写入roles 声明。更改用户的应用角色分配后,变更会在该用户获取新令牌时生效。已签发的令牌在过期前仍保留原有角色。如果使用 Azure CLI,可运行 az logout 和 az login 立即获取新令牌。
故障排查
令牌被拒绝,且其签发方以 https://sts.windows.net 开头
令牌被拒绝,且其签发方以 https://sts.windows.net 开头
Entra ID 签发的是 v1.0 令牌。请按照请求 v2.0 访问令牌中的说明,在应用程序清单中将
requestedAccessTokenVersion 设置为 2,然后重新请求令牌。令牌因受众不匹配而被拒绝
令牌因受众不匹配而被拒绝
- ClickHouse Cloud 中该提供商的 Audience 必须是客户端 ID,而不是
api://<CLIENT_ID>。 - 请确认您请求的是 ClickHouse 应用程序的令牌。如果未指定
--resource,az account get-access-token返回的将是 Azure Resource Manager 的令牌。
Entra ID 返回 AADSTS65001 或要求同意授权
Entra ID 返回 AADSTS65001 或要求同意授权
客户端应用程序未获得
access_as_application 作用域的预授权。请按照授权客户端应用程序进行用户登录中的说明,在 Expose an API → Authorized client applications 下添加其客户端 ID。Entra ID 返回 AADSTS50105 或 AADSTS501051
Entra ID 返回 AADSTS50105 或 AADSTS501051
该用户或应用程序未分配给 ClickHouse 应用程序,且 Assignment required? 设置为 Yes。请将该用户、其所属的某个组或该应用程序分配给一个应用角色。如果分配的是组,请确保该用户是该组的直接成员。
身份验证成功,但查询因 ACCESS_DENIED 失败
身份验证成功,但查询因 ACCESS_DENIED 失败
临时用户缺少执行该查询所需的特权。请检查以下各项:
- 提供商的 Roles claim 已设置为
roles。 - 令牌中包含
roles声明。如果调用方被分配给应用程序时未指定应用角色,令牌中就不会有该声明。 roles声明中的每个值都与服务上现有的 ClickHouse 角色完全匹配 (区分大小写) 。default用户拥有您授予该角色的特权。
配置声明映射策略后令牌被拒绝
配置声明映射策略后令牌被拒绝
如果您为应用程序配置了声明映射策略或自定义签名私钥,Entra ID 签发令牌时所用的私钥将不在该 tenant 的 JWKS 中。请将提供商的 JWKS URL 设置为
https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys?appid=<CLIENT_ID>。相关内容
- JWT 身份验证设置:在 Cloud 控制台中添加、更新和删除 JWT 提供商。
- JWT 身份验证:令牌声明、临时用户及客户端使用方法。