Apache Pulsar 授权机制与 ACL 管理实战指南:从 Broker/Proxy 配置到租户与命名空间权限
Apache Pulsar 授权机制与 ACL 管理实战指南:从 Broker/Proxy 配置到租户与命名空间权限
Apache Pulsar 在默认情况下不开启任何加密、认证或授权,任何客户端都可以通过明文服务地址访问集群。本文以 Pulsar 2.2.1 版本的安全授权文档为核心,系统讲解授权(Authorization)与认证(Authentication)的区别、Broker 与 Proxy 上的授权配置、超级用户(superuser)与代理角色(proxy role)的设定,以及如何通过 pulsar-admin 和 Java Admin API 完成租户创建、权限授予与撤销。读完本文,你将能够为生产集群搭建一套完整的基于角色(role)的 ACL 授权体系。
授权在 Pulsar 安全体系中的位置
在 Pulsar 中,认证(Authentication)负责"确认客户端是谁":认证提供者(Authentication Provider)在建立连接时校验客户端凭据,并将客户端与一个 角色令牌(role token) 关联起来。角色(role)本质上是一个字符串,例如 admin 或 app1,它可以代表单个客户端,也可以代表一组客户端,用于控制这些客户端能否向特定 Topic 生产或消费消息、能否管理租户配置等。
认证 ≠ 授权:如果只开启认证,任何一个通过认证的角色令牌都可以访问集群中的所有资源。**授权(Authorization)**才是决定"客户端具体能做什么"的过程,也就是对角色执行 ACL 检查的过程。默认情况下 Pulsar 不会配置加密、认证或授权,任何客户端都可以通过明文 Service URL 访问,因此对于生产环境必须显式启用这些安全特性。
角色层级:超级用户与租户管理员
- 超级用户(superusers):拥有最高权限的角色。超级用户既可以创建和销毁租户(tenant),也可以完全访问所有租户下的全部资源。
- 租户管理员(tenant admin):当超级用户创建租户时,会为这个租户指定一个 admin 角色。持有该 admin 角色令牌的客户端,可以在该租户内创建、修改、销毁命名空间(namespace),并可以对其中的其他角色令牌授予或撤销权限。
从源码结构看,这一套角色判断逻辑由 AuthorizationService 统一承载:isSuperUser 检查角色是否位于 broker 配置的 superUserRoles 中;isTenantAdmin 则检查角色是否出现在租户信息(TenantInfo)的 adminRoles 列表中,对应的实现定义在 AuthorizationProvider 接口的默认方法里。
Broker 与 Proxy 的授权设置
在 Broker 上启用授权并指定超级用户
授权开关和超级用户列表都配置在 broker 配置文件 conf/broker.conf 中:
authorizationEnabled=true
superUserRoles=my-super-user-1,my-super-user-2
从仓库中的 broker.conf 可以看到,与该功能相关的一组完整参数如下:
| 配置项 | 默认值 | 说明 |
|---|---|---|
authenticationEnabled |
false |
是否启用认证。授权依赖认证先行,通常需要同时开启 |
authenticationProviders |
(空) | 认证提供者类名列表(逗号分隔),例如 TLS、Athenz、JWT 等 |
authorizationEnabled |
false |
是否强制执行授权检查 |
authorizationProvider |
org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider |
授权提供者全限定类名 |
superUserRoles |
(空) | 被视为"超级用户"的角色列表,可执行所有 admin 操作并可向所有 Topic 发布/消费 |
proxyRoles |
(空) | 被视为"代理角色"的角色列表,见下文 Proxy Roles 章节 |
authorizationAllowWildcardsMatching |
false |
是否允许在角色名中使用通配符匹配(仅当 * 出现在角色名的首尾位置时生效) |
需要注意的是,superUserRoles 通常不仅用于管理员与业务客户端,还用于 broker 与 broker 之间的授权。当启用 geo-replication(跨集群复制) 时,每个 broker 都需要能够向其他集群的所有 Topic 发布消息,因此这些 broker 的身份必须被纳入可授权的角色范围。
在 Proxy 上启用授权
如果集群前端部署了 Pulsar Proxy,可以在代理配置文件 conf/proxy.conf 中同样启用授权:
authorizationEnabled=true
superUserRoles=
authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider
关键语义在于:授权是分层叠加的。一旦在 Proxy 上启用了授权,Proxy 在把请求转发给 Broker 之前会先做一次额外的授权检查;而如果 Broker 上也启用了授权,Broker 收到转发过来的请求时还会再校验一次。也就是说,请求会经过"Proxy 检查 + Broker 检查"两道关卡。
另外 proxy.conf 中还提供了 forwardAuthorizationCredentials(默认 false)配置:当设为 true 时,Proxy 会把客户端的授权凭据转发给 Broker 做二次授权,但该选项仅在 authenticationEnabled=true 时生效。
Proxy Roles 与 Original Principal:代理场景下的身份透传
问题背景
默认情况下,Broker 会把"Proxy 与 Broker 之间的连接"当作一个普通用户连接来处理,即 Broker 把用户认证为 proxy.conf 中配置的角色(具体参见 TLS 认证文档中关于 Proxy 的配置,该章节描述了 proxy 需要拥有自己的客户端密钥对,并且这个密钥对对应的角色令牌应配置到 broker 的 proxyRoles 中)。但用户通过 Proxy 连接集群时,通常并不想向 Broker 再次认证——用户期望的是:以自己向 Proxy 认证时的角色身份与集群交互。
工作原理
Pulsar 用 Proxy roles 机制来实现这种身份透传。proxyRoles 在 broker 配置文件 conf/broker.conf 中指定。其规则是:
- 如果一个与 Broker 完成认证的客户端角色位于
proxyRoles列表中,那么这个客户端的所有请求必须同时携带它经由 Proxy 认证所获得的客户端角色信息,这个信息被称为 original principal(原始主体); - 如果请求中缺少 original principal,该客户端将无法访问任何资源。
这段校验逻辑在 AuthorizationService.isValidOriginalPrincipal 中实现:当 authenticatedPrincipal 属于 proxyRoles 时,若 original principal 为空,或 original principal 本身也是一个 proxy role,则校验失败;反过来,非 proxy 角色携带了与自身不同的 original principal 也会被记录告警。
代理角色的两种授权策略
要让资源能通过 Proxy 被访问,proxy role 和 original principal 都必须被授权访问该资源。管理员通常有两种做法:
方式一(更安全):每次授权资源时,同时授权 proxy role。 例如有一个名为 proxy1 的代理角色,那么当超级用户创建租户时,应该把 proxy1 也指定为 admin role 之一;当给某个角色授予在某个命名空间生产/消费的权限时,如果该客户端要通过 Proxy 生产/消费,则必须给 proxy1 授予同样的权限。这样保证"资源 + 代理通道"两重授权都到位。
方式二(更便捷但有风险):把 proxy role 设为超级用户。 这允许 Proxy 访问所有资源。客户端仍然需要先向 Proxy 认证,而且所有经 Proxy 发出的请求,其角色都会被降级为认证客户端的 original principal。但隐患在于:一旦 Proxy 被攻破,攻击者就能获得集群的完整访问权。
在 conf/broker.conf 中按如下方式配置代理角色:
proxyRoles=my-proxy-role
# 如果希望允许超级用户也使用 Proxy(参见上文方式二)
superUserRoles=my-super-user-1,my-super-user-2,my-proxy-role
结合源码可以看到,AuthorizationService 在处理 proxy 场景时对 canProduceAsync、canConsumeAsync、canLookupAsync 以及各 allowXxxOperationAsync 方法都会执行"角色授权 && 原始主体授权"的双重判定(thenCombine 逻辑),这正是"两层都通过才放行"原则的代码级体现。
管理租户(Tenant)
Pulsar 实例(instance)的管理员或某种自助服务门户,通常会负责为使用者"开通"一个 租户(tenant)。租户的创建与管理通过 pulsar-admin 命令行工具完成。
创建租户
下面的示例创建了一个名为 my-tenant 的租户,并允许它使用 us-west 和 us-east 两个集群:
$ bin/pulsar-admin tenants create my-tenant \
--admin-roles my-admin-role \
--allowed-clusters us-west,us-east
--admin-roles:指定租户的 admin 角色。能够以my-admin-role身份通过认证的客户端,可以执行该租户下的所有管理任务(创建/修改/销毁命名空间,授予与撤销权限等)。--allowed-clusters:指定该租户可用的集群列表,用于多集群(含 geo-replication)场景下约束租户的资源边界。
这两个参数在 CmdTenants.java 中对应 --admin-roles 与 --allowed-clusters 的注解定义,最终通过 getAdmin().tenants().createTenant(tenant, tenantInfo) 下发创建请求。
租户、命名空间与 Topic 的层级关系
Pulsar 的 Topic 名称结构直接反映了租户、集群、命名空间之间的层级关系:
persistent://tenant/namespace/topic
其中 tenant 是租户名,namespace 是租户下的命名空间名,topic 是具体的主题名。这个层级也正是 ACL 授权的作用域基础:租户级权限管理租户配置,命名空间级权限统管该命名空间下所有 Topic,Topic 级权限则精确到单个主题。
管理权限(Permissions)
在 Pulsar 中,权限既可以授予到命名空间级别(该命名空间下的所有 Topic 均生效),也可以授予到 Topic 级别(仅对指定 Topic 生效)。完整的管理操作可以参考 Admin API 权限管理文档,这里整理最常用的三种操作:
授予权限
使用 pulsar-admin 的 grant-permission 子命令,通过 --actions 指定操作(如 produce、consume),通过 --role 指定角色:
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
--actions produce,consume \
--role admin10
通配符授权:当 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、my.role.bar 等角色都可以生产/消费。同样:
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
--actions produce,consume \
--role '*.role.my'
则使 1.role.my、2.role.my、foo.role.my、bar.role.my 等角色获得权限。注意:如果通配符出现在角色名中间,例如 my.*.role,那么只有字面角色 my.*.role 本身获得权限,my.1.role、my.2.role 等不会被匹配。
查看权限
使用 permissions 子命令查看某个命名空间下各角色已获授的权限:
$ pulsar-admin namespaces permissions test-tenant/ns1
{
"admin10": [
"produce",
"consume"
]
}
撤销权限
使用 revoke-permission 子命令,通过 --role 指定要撤销的角色:
$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
--role admin10
撤销后,该角色将不再拥有对该命名空间的访问权限。
Pulsar Admin 客户端认证(Java API)
管理操作除了通过命令行,也可以使用 Java Admin API 编程完成。此时需要在构建 PulsarAdmin 客户端时指定认证插件与参数:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("http://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.build();
当 Broker 启用了 TLS 传输时,使用 HTTPS 服务地址并配置信任证书路径:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("https://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.tlsTrustCertsFilePath("/path/to/trust/cert")
.build();
其中 authentication 的第一个参数是认证插件类的全限定名(与 conf/broker.conf 中 authenticationProviders 配置的插件一致),第二个参数是插件所需的键值参数。tlsTrustCertsFilePath 指向用于校验 Broker 服务端证书的 CA 信任证书,保证管理通道本身也是加密可信的。基于此 admin 对象,即可调用 admin.tenants().createTenant(...)、admin.namespaces().grantPermissionOnNamespace(...)、admin.namespaces().revokePermissionsOnNamespace(...) 等方法完成与命令行等价的管理操作。
小结
Pulsar 的授权体系以"角色(role)"为最小授权单位,通过 conf/broker.conf 中的 authorizationEnabled 与 superUserRoles 打开总开关并设定最高权限角色;在接入 Proxy 的部署中,通过 proxyRoles 与 original principal 实现客户端身份透传,并采用"proxy role 与 original principal 双重授权"的安全策略;租户、命名空间、Topic 的三级资源模型则提供了从粗粒度到细粒度的 ACL 管控能力。配合 pulsar-admin 命令行与 Java Admin API,即可在生产集群中落地完整的授权与访问控制方案。