Apache Pulsar 授权机制与 ACL 管理实战指南:从 Broker/Proxy 配置到租户与命名空间权限

原创2026-09-26 19:18:511,912 阅读
文章标签:消息队列后端流处理

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,即可在生产集群中落地完整的授权与访问控制方案。

登录后查看全文
pulsar