Apache Pulsar 授权与 ACL 配置实战:Broker/Proxy 授权、代理角色与租户权限管理
Apache Pulsar 授权与 ACL 配置实战:Broker/Proxy 授权、代理角色与租户权限管理
Apache Pulsar 的授权(Authorization)机制在完成客户端身份认证之后,进一步回答"该客户端能做什么"的问题:它决定一个持有角色令牌(role token)的客户端能否创建租户、能否对某个命名空间或主题执行生产(produce)、消费(consume)等操作。本文以 site2/website-next/versioned_docs/version-2.1.1-incubating/security-authorization.md 为主线,结合本仓库中的 conf/broker.conf、conf/proxy.conf 以及授权相关的源码实现,系统讲解如何在 Broker 与 Proxy 上启用授权、如何配置超级用户(superuser)与代理角色(proxy roles)、如何通过 pulsar-admin 管理租户与权限,并给出 PulsarAdmin 客户端启用认证的 Java 代码示例。读完本文,你将能够为 Pulsar 集群搭建一套从"认证"到"授权"的完整访问控制方案。
授权在 Pulsar 安全体系中的位置
Pulsar 的安全体系分为两层:认证(Authentication)与授权(Authorization)。
- 认证:由认证提供方负责识别客户端身份,并把客户端与一个角色令牌(role token)关联起来。角色是一个字符串,例如
admin或app1,可以代表单个或多个客户端。目前 Pulsar 支持 TLS、Athenz、Kerberos、JWT 等认证提供方。 - 授权:如果只启用认证,那么任何通过认证的角色令牌都能访问集群中的所有资源。授权才是决定"客户端能做什么"的过程。
权限最高的角色令牌被称为超级用户(superuser)。超级用户可以创建和销毁租户(tenant),并且拥有对所有租户资源的完全访问权限。
当超级用户创建一个租户时,该租户会被分配一个管理员角色(admin role)。持有管理员角色令牌的客户端可以创建、修改和销毁命名空间(namespace),也可以把权限授予或撤销给该命名空间下的其他角色令牌。
从源码看,授权的能力边界由 AuthorizationProvider.java 接口定义,它提供了 isSuperUser、isTenantAdmin、canProduceAsync、canConsumeAsync 等核心方法;默认实现为 org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider(见 conf/broker.conf 中 authorizationProvider 配置项)。此外还有支持多角色令牌的 MultiRolesTokenAuthorizationProvider 等扩展实现。这意味着授权行为是可插拔的,你可以在不改动 Broker 主流程的前提下替换授权策略。
Broker 与 Proxy 授权配置
启用授权并指定超级用户
授权能力默认是关闭的。你可以在 Broker 的配置文件(conf/broker.conf)中启用授权并指定超级用户角色:
authorizationEnabled=true
superUserRoles=my-super-user-1,my-super-user-2
conf/broker.conf 中对应的完整配置段(约 721–745 行)如下,它同时也给出了相关参数的默认值:
### --- Authentication --- ###
# Enable authentication
authenticationEnabled=false
# Authentication provider name list, which is comma separated list of class names
authenticationProviders=
# Interval of time for checking for expired authentication credentials
authenticationRefreshCheckSeconds=60
# Enforce authorization
authorizationEnabled=false
# Authorization provider fully qualified class-name
authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
# Allow wildcard matching in authorization
# (wildcard matching only applicable if wildcard-char:
# * presents at first or last position eg: *.pulsar.service, pulsar.service.*)
authorizationAllowWildcardsMatching=false
# Role names that are treated as "super-user", meaning they will be able to do all admin
# operations and publish/consume from all topics
superUserRoles=
几个关键参数的含义:
| 参数 | 默认值 | 说明 |
|---|---|---|
authorizationEnabled |
false |
是否在 Broker 上强制执行授权检查 |
authorizationProvider |
org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider |
授权提供方的全限定类名,用于自定义授权逻辑 |
superUserRoles |
空 | 被视为超级用户的角色列表,逗号分隔;这些角色可以执行所有管理操作,并在所有主题上生产/消费 |
authorizationAllowWildcardsMatching |
false |
是否允许角色名通配符匹配(通配符 * 只能出现在角色名的开头或结尾,例如 *.pulsar.service) |
authenticationRefreshCheckSeconds |
60 |
检查认证凭证过期状态的间隔时间,过期后 Broker 会强制重新认证 |
在 AuthorizationProvider.java 中,isSuperUser 的默认实现正是把角色与 ServiceConfiguration.getSuperUserRoles() 集合比对:只要 role != null && superUserRoles.contains(role) 即视为超级用户。因此 superUserRoles 是决定"谁拥有集群最高权限"的直接依据,务必只授予受信任的身份。
完整的参数列表见
conf/broker.conf文件,各参数的默认值也可参考 reference-configuration.md 中的 Broker 配置章节。
典型的超级用户使用场景包括:管理员账号、客户端,以及 Broker 与 Broker 之间的授权。当启用地理复制(geo-replication)时,每个 Broker 都需要能向其他集群的所有主题发布消息,因此复制链路涉及的角色需要具备相应权限。
在 Proxy 上启用授权
你也可以在 Proxy 配置文件(conf/proxy.conf)中启用授权。一旦在 Proxy 上启用授权,Proxy 会在把请求转发给 Broker 之前额外执行一次授权检查;而如果 Broker 上也启用了授权,Broker 收到转发过来的请求时还会再检查一次请求的授权。因此形成了"Proxy 前置检查 + Broker 二次检查"的双层防线。
conf/proxy.conf 中与授权相关的配置段(约 132–146 行):
### ---Authorization --- ###
# Role names that are treated as "super-users," meaning that they will be able to perform all admin
# operations and publish/consume to/from all topics (as a comma-separated list)
superUserRoles=
# Whether authorization is enforced by the Pulsar proxy
authorizationEnabled=false
# Authorization provider as a fully qualified class name
authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
# Whether client authorization credentials are forwared to the broker for re-authorization.
# Authentication must be enabled via authenticationEnabled=true for this to take effect.
forwardAuthorizationCredentials=false
注意 forwardAuthorizationCredentials 参数:它决定 Proxy 是否把客户端的授权凭证转发给 Broker 做二次授权。该参数仅在 authenticationEnabled=true 时生效。
Proxy Roles:代理角色与原始主体
为什么需要代理角色
默认情况下,Broker 会把 Proxy 与 Broker 之间的连接当作一个普通用户连接来处理,即 Broker 会把通过该连接进入的用户认证为 proxy.conf 中配置的角色(参见 security-tls-authentication.md 中关于 TLS 认证下为 Proxy 配置客户端密钥对并把其角色放入 proxyRoles 的说明)。然而,用户通过 Proxy 连接到集群时,并不希望自己以 Proxy 的身份被识别——他们期望以自己在 Proxy 处完成认证时所用的角色与集群交互。
Pulsar 通过 Proxy roles(代理角色) 机制来解决这个问题。Proxy roles 在 Broker 配置文件(conf/broker.conf)中指定。规则如下:
- 如果一个与 Broker 完成认证的客户端,其角色是
proxyRoles中的某一个,那么该客户端发出的所有请求都必须额外携带它在 Proxy 处认证得到的客户端角色信息; - 这个信息被称为原始主体(original principal);
- 如果请求中缺少原始主体,那么该客户端无法访问任何资源。
conf/broker.conf 中对应的配置(约 591–594 行):
### --- Authentication --- ###
# Role names that are treated as "proxy roles". If the broker sees a request with
# role as proxyRoles - it will demand to see a valid original principal.
proxyRoles=
与之配套的还有 authenticateOriginalAuthData 参数:若置为 true,Broker 会认证请求中携带的原始认证数据;否则仅接受并(按需)授权 originalPrincipal。
授权 Proxy 角色与原始主体的两种策略
要让资源能够通过 Proxy 被访问,Proxy 角色(proxy role)和原始主体(original principal)两者都必须被授权。管理员可以采取两种策略:
策略一:为每个资源显式授权 Proxy 角色(更安全)
每次授予资源访问权时,同时把 Proxy 角色一并授予。例如,假设 Proxy 角色名为 proxy1:
- 当超级用户创建租户时,把
proxy1指定为该租户的管理员角色之一; - 当某个角色被授予在某个命名空间上生产或消费的权限时,如果该客户端希望通过 Proxy 生产或消费,则需要给
proxy1授予相同的权限。
策略二:把 Proxy 角色设为超级用户(更简单但有风险)
把 Proxy 角色加入 superUserRoles,使 Proxy 可以访问所有资源。客户端仍然需要在 Proxy 处完成认证,而且所有经由 Proxy 发出的请求,其角色都会被"降级"为已认证客户端的原始主体。风险在于:如果 Proxy 被攻破,攻击者就能获得集群的完全访问权限。
配置示例(conf/broker.conf):
proxyRoles=my-proxy-role
# if you want to allow superusers to use the proxy (see above)
superUserRoles=my-super-user-1,my-super-user-2,my-proxy-role
源码层面的校验逻辑
原始主体与代理角色的合法性校验实现在 AuthorizationService.java 的 isValidOriginalPrincipal 方法中,其核心规则与文档描述完全一致:
- 如果
authenticatedPrincipal在proxyRoles中,则必须提供originalPrincipal,否则校验失败,报错 "originalPrincipal must be provided when connecting with a proxy role."; - 如果
originalPrincipal本身也在proxyRoles中,则校验失败,报错 "originalPrincipal cannot be a proxy role."; - 非 Proxy 角色携带
originalPrincipal时(且两者不相等)会记录警告日志,提示该行为在未来的版本中不再被允许。
在 ServerCnx.java 中,originalPrincipal 作为连接级字段维护(第 194 行),并在认证握手时从 ConnectCommand 中提取(第 882–892 行)。Broker 在后续所有授权检查(如生产、消费、命名空间操作)中都会同时考量 authRole 与 originalPrincipal——例如 ServerCnx.java 中同时校验 isSuperUser(originalPrincipal, ...) 与 isSuperUser(authRole, ...) 两个结果。这意味着即使连接方是超级用户 Proxy,请求实际生效的权限仍然取决于其携带的原始主体。
管理租户(Administer Tenants)
Pulsar 的租户(tenant)是一个用于分配容量、实施认证/授权方案的管理单元。租户通常由 Pulsar 集群的管理员或某种自助服务门户来创建。
租户的管理统一通过 pulsar-admin 工具完成。
创建新租户
以下是一个租户创建命令示例:
$ bin/pulsar-admin tenants create my-tenant \
--admin-roles my-admin-role \
--allowed-clusters us-west,us-east
该命令创建了一个名为 my-tenant 的新租户,它被允许使用 us-west 和 us-east 两个集群。能够以 my-admin-role 角色通过认证的客户端,被允许在该租户上执行所有管理任务。
命令的实现位于 CmdTenants.java:create 子命令解析 --admin-roles(-r)与 --allowed-clusters 参数,构造 TenantInfoImpl(adminRoles 与 allowedClusters 集合)后调用 getAdmin().tenants().createTenant(tenant, tenantInfo)。其背后对应管理 API 的 POST /admin/v2/tenants/:tenant 接口,以及 Java 管理 API 的 admin.tenants().createTenant(tenantName, tenantInfo)(详见 admin-api-tenants.md)。
补充说明:
--admin-roles支持逗号分隔的多个角色,例如--admin-roles role1,role2,role3;- 如果省略
--allowed-clusters,从源码(CmdTenants.java)可以看到,命令会回退为当前集群列表中所有可用集群; - 租户的
adminRoles直接决定了AuthorizationProvider.isTenantAdmin的判定结果——见 AuthorizationProvider.java,它检查tenantInfo.getAdminRoles().contains(role)。
主题名称的层级结构
Pulsar 主题名称的结构反映了租户、集群、命名空间之间的层级关系:
persistent://tenant/namespace/topic
tenant:租户,是容量分配与认证/授权方案的实施单元;namespace:命名空间,一组属于同一租户的主题的虚拟分组,也是权限授予的基本粒度之一;topic:主题,消息生产与消费的实际载体。
因此,授权模型天然是分层的:租户管理员 > 命名空间权限 > 主题权限。
管理权限(Manage Permissions)
权限的授予、查询与撤销可以使用 Pulsar 的管理工具完成,详见 admin-api-permissions.md。Pulsar 支持两种粒度的授权:
- 命名空间级权限:授予后,用户可访问该命名空间下的所有主题;
- 主题级权限:授予后,用户只能访问该主题。
以下为命名空间级权限的常用操作示例:
授予权限(produce 与 consume):
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
--actions produce,consume \
--role admin10
对应 REST API 为 POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role,Java API 为 admin.namespaces().grantPermissionOnNamespace(namespace, role, authActions)。
查看权限:
$ pulsar-admin namespaces permissions test-tenant/ns1
{
"admin10": [
"produce",
"consume"
]
}
对应 REST API 为 GET /admin/v2/namespaces/:tenant/:namespace/permissions,Java API 为 admin.namespaces().getPermissions(namespace)。
撤销权限:
$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
--role admin10
对应 REST API 为 DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role,Java API 为 admin.namespaces().revokePermissionsOnNamespace(namespace, role)。
角色名通配符:当 conf/broker.conf 中的 authorizationAllowWildcardsMatching=true 时,可以使用通配符 * 进行批量授权。通配符只能出现在角色名的开头或结尾:
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
--actions produce,consume \
--role 'my.role.*'
上述命令使 my.role.1、my.role.2、my.role.foo 等角色都可以生产与消费。类似地,*.role.my 可匹配 1.role.my、foo.role.my 等。但中间通配符不生效——例如 my.*.role 只匹配字面角色 my.*.role,而 my.1.role 等无法获得权限。
Pulsar Admin 客户端认证
管理 API 的调用方(例如自动化运维脚本或管理平台)同样需要携带认证信息。PulsarAdmin 客户端通过 authentication 方法指定认证插件类及参数:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("http://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.build();
如果需要使用 TLS 加密管理通道,则在 builder 中额外配置信任证书路径,并把服务地址切换为 HTTPS:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("https://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.tlsTrustCertsFilePath("/path/to/trust/cert")
.build();
其中:
serviceHttpUrl:Broker 的 HTTP 管理服务地址(http或https取决于是否启用 TLS);authentication:第一个参数是认证插件类的全限定名(如org.apache.pulsar.client.impl.auth.AuthenticationTls),第二个参数是插件参数(param1:value1形式的键值对,例如tlsCertFile:...,tlsKeyFile:...);tlsTrustCertsFilePath:TLS 模式下用于校验服务端证书的信任证书路径。
完整配置清单与检查要点
要在集群中落地一套授权方案,建议按以下顺序检查:
- Broker 配置(conf/broker.conf):确认
authenticationEnabled=true、authenticationProviders已填写,然后设置authorizationEnabled=true、superUserRoles、proxyRoles(若存在 Proxy 部署); - Proxy 配置(conf/proxy.conf):确认
authenticationEnabled=true,并按需设置authorizationEnabled=true、superUserRoles、forwardAuthorizationCredentials; - 授权提供方:默认使用
org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider,如需多角色令牌等能力可替换为MultiRolesTokenAuthorizationProvider等实现,或基于 AuthorizationProvider.java 接口自行扩展; - 租户与权限:使用
bin/pulsar-admin tenants create创建租户并分配--admin-roles,再通过namespaces grant-permission/revoke-permission/permissions管理命名空间级权限; - 客户端侧:生产/消费客户端携带各自角色对应的认证凭证;管理类调用方使用
PulsarAdmin.builder().authentication(...)配置认证插件。
需要注意的边界条件:授权依赖认证先行,未启用认证时角色令牌无从谈起;superUserRoles 中的角色拥有全集群最高权限,应严格限定在受信任的管理员、运维组件与 Broker 间复制链路使用;把 Proxy 角色加入 superUserRoles 虽然便捷,但会显著放大 Proxy 被攻破时的风险,应优先采用"逐资源显式授权 Proxy 角色"的方式。