Apache Pulsar 授权与 ACL 实战指南:从认证到细粒度访问控制
Apache Pulsar 授权与 ACL 实战指南:从认证到细粒度访问控制
Pulsar 的授权(Authorization)与访问控制列表(ACL)机制负责回答"已通过认证的客户端能对哪些资源做什么"这一问题:只有同时启用认证与授权,才能将 role token 与具体的租户、命名空间、主题权限绑定起来。本文基于 security-authorization.md 展开,结合 broker/proxy 配置、授权提供者源码与测试用例,系统讲解 superuser、Proxy Roles、租户管理与权限授予的完整落地路径,读完即可在生产环境完成从"只开启认证"到"细粒度授权"的升级。
认证与授权的关系:role token 决定了"你能做什么"
在 Pulsar 中,认证提供者 负责正确识别客户端身份,并把客户端与 role token 关联起来。如果只启用认证而不启用授权,任何一个持有合法 role token 的客户端都能访问集群中的所有资源——认证只是解决了"你是谁"的问题,没有解决"你能做什么"的问题。而授权正是决定客户端能够执行哪些操作的过程,它建立在认证之上,两者缺一不可。
授权模型中,权限最高的角色称为 superuser(超级用户)。superuser 可以创建和销毁租户,并拥有对所有租户资源的完整访问权限。
权限的层级结构如下:
- superuser:拥有全部权限,可创建/销毁租户,可访问所有租户资源;
- tenant admin(租户管理员):superuser 创建租户时被指定为该租户的 admin role,持有该 role token 的客户端可以创建、修改、销毁该租户下的命名空间,并可以对这些命名空间授予或撤销其他 role token 的权限;
- 普通 role:仅拥有被显式授予的命名空间级或主题级权限。
从源码看,这一"先查 superuser、再查租户 admin、最后查 ACL"的判定链在 AuthorizationService.java 中通过 isSuperUser / isTenantAdmin 逐级实现;而 canProduceAsync、canConsumeAsync、canLookupAsync 等方法在执行任何资源操作前都会先检查 conf.isAuthorizationEnabled(),只有授权开启时才进入 provider.isSuperUser(...) 的判定,否则直接放行(见 AuthorizationService.java)。
Pulsar 的 topic 名称结构本身也体现了租户、命名空间、主题的层级关系:
persistent://tenant/namespace/topic
Broker 与 Proxy 的授权配置
启用授权并指定 superuser
在 broker 的配置文件 conf/broker.conf 中开启授权并指定 superuser:
authorizationEnabled=true
superUserRoles=my-super-user-1,my-super-user-2
在 conf/broker.conf 中,与授权直接相关的完整参数块位于 ### --- Authentication --- ### 段落(conf/broker.conf#L721-L745),包括:
| 参数 | 默认值 | 说明 |
|---|---|---|
authenticationEnabled |
false |
是否启用认证,授权通常依赖认证已开启 |
authenticationProviders |
空 | 认证提供者类名列表,逗号分隔 |
authorizationEnabled |
false |
是否强制启用授权检查 |
authorizationProvider |
org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider |
授权提供者全限定类名 |
authorizationAllowWildcardsMatching |
false |
是否允许授权中的通配符匹配(通配符 * 只能出现在角色名的首部或尾部,如 *.pulsar.service、pulsar.service.*) |
superUserRoles |
空 | 被视为 superuser 的角色列表,可执行所有 admin 操作并可从所有 topic 发布/消费 |
proxyRoles |
空 | 被视为 proxy 角色的角色名(见下文 Proxy Roles 章节) |
authenticateOriginalAuthData |
false |
若为 true,broker 会认证原始的认证数据;否则只接受 originalPrincipal 并在需要时对其进行授权(conf/broker.conf#L596-L598) |
anonymousUserRole |
空 | 当此参数非空时,未认证用户以该角色身份操作 |
典型的用法是:将 superuser 角色用于管理员、普通客户端以及 broker 之间的相互授权。当使用地理复制时,每个 broker 都需要能够向其他集群的所有 topic 发布消息,此时也必须为 broker 配置相应的 superuser 或授权。
Proxy 侧的授权开关
也可以在代理配置文件 conf/proxy.conf 中启用授权。一旦在 proxy 上启用授权,proxy 在把请求转发给 broker 之前会额外做一次授权检查;而如果在 broker 上也启用了授权,broker 收到被转发过来的请求时还会再校验一次该请求的授权。也就是说,两者可以形成"双层校验"。
conf/proxy.conf 中的授权参数(conf/proxy.conf#L132-L146):
# 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 forwarded 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 中配置的角色(参见 TLS 认证文档)。但客户端通过 proxy 连接集群时,通常并不希望自己"变成"proxy 的身份——客户端期望能以自己向 proxy 认证时的那个角色与集群交互。
为此 Pulsar 引入了 Proxy Roles 机制,在 broker 配置文件的 proxyRoles 中指定。规则是:如果某个与 broker 完成认证的客户端身份属于 proxyRoles,那么该客户端发出的所有请求还必须携带"与 proxy 认证的客户端角色"信息,这个信息称为 original principal(原始主体)。如果缺少 original principal,该客户端将无法访问任何资源。
从 AuthorizationService.java 的 isValidOriginalPrincipal 实现可以看到该校验逻辑非常严格:
- 当认证主体
authenticatedPrincipal属于proxyRoles时,必须提供非空的originalPrincipal,否则校验失败; originalPrincipal不能本身也是一个 proxy 角色;- 非 proxy 角色不应携带 originalPrincipal(未来版本将直接拒绝)。
上述规则同样被 AuthorizationTest.java 中的 testOriginalRoleValidation 测试用例逐一验证,例如 isValidOriginalPrincipal("proxy", "", ...) 返回 false,而 isValidOriginalPrincipal("proxy", "client", ...) 返回 true。
同时为 proxy role 与 original principal 授权
要让资源能通过 proxy 被访问,必须同时为 proxy role 和 original principal 授权。管理员通常有两种做法:
**方式一(更安全):每次授予资源权限时,同时把 proxy role 也授权一次。**例如有一个名为 proxy1 的 proxy 角色,那么当 superuser 创建租户时,应该把 proxy1 也指定为 admin roles 之一;当某个角色被授予从某命名空间 produce/consume 的权限、且该客户端希望通过 proxy 生产/消费时,也应给 proxy1 授予相同的权限。
**方式二(更便捷但有风险):把 proxy role 直接设为 superuser。**这样 proxy 可以访问所有资源。客户端仍然需要向 proxy 认证,所有经由 proxy 的请求其角色都会被降级为已认证客户端的 original principal。但代价是:一旦 proxy 被攻破,攻击者将获得集群的完全访问权限,因此该方式仅适用于安全要求不高的场景。
在 conf/broker.conf 中配置 proxy roles 的示例:
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
需要注意的是,由于 broker 会对 proxy role 和 original principal 做双重授权判定(isRoleAuthorized && isOriginalAuthorized,见 AuthorizationService.java),在方式二下即便 proxy 是 superuser,客户端自身的角色也必须拥有相应权限,否则依然会被拒绝。
租户管理:创建租户与指定 admin 角色
Pulsar 实例 的管理员或某种自助服务平台通常负责创建 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 角色的客户端,都被允许对该租户执行全部管理任务。
从 CLI 源码看,CmdTenants.java 中 Create 命令支持两个关键参数:
--admin-roles/-r:允许管理该租户的认证主体列表,逗号分隔;--allowed-clusters/-c:允许使用的集群列表,逗号分隔;如果为空,则默认继承当前getAdmin().clusters().getClusters()返回的全部可用集群。
命令内部通过 TenantInfoImpl 携带这两组信息调用 admin.tenants().createTenant(tenant, tenantInfo) 完成创建。对应的更新命令 tenants update 也支持 --admin-roles 与 --allowed-clusters,用于动态调整租户配置。
在启用授权的集群中,只有 superuser(或具备相应租户管理权限的角色)才能创建/删除租户;租户 admin role 则可在其租户内创建命名空间并管理 ACL。
管理权限:命名空间与主题级 ACL
使用 Admin 工具管理权限
权限管理(grant / revoke)可通过 Pulsar Admin Tools 完成,支持命名空间级和主题级两种粒度:
- 命名空间级授权:向命名空间的 ACL 写入某角色与
AuthAction集合的映射; - 主题级授权:向命名空间策略中特定 topic 的 ACL 写入映射;
- 订阅级授权:限制哪些角色可以操作特定 subscription。
从 PulsarAuthorizationProvider.java 的实现可见,grantPermissionAsync 通过 pulsarResources.getNamespaceResources().setPoliciesAsync(...) 将授权策略持久化到 auth_policies 结构中:命名空间权限写入 namespaceAuthentication,主题权限写入 topicAuthentication(键为完整 topic URI),订阅权限写入 subscriptionAuthentication。
在消费侧,canConsumeAsync 还会额外检查两类订阅约束(PulsarAuthorizationProvider.java):
- 订阅级授权列表:若某 subscription 配置了角色白名单,则角色必须出现在其中才能订阅;
subscription_auth_mode为Prefix时:订阅名必须以认证角色为前缀(如角色role1的订阅名必须是role1-xxx),否则拒绝创建 consumer。该行为同样被 AuthorizationTest.java 中的测试覆盖。
权限判定还支持通配符:当开启 authorizationAllowWildcardsMatching=true 后,* 只能位于角色名首部或尾部,如 *.pulsar.service(前缀匹配)或 pulsar.service.*(后缀匹配),具体实现见 checkWildcardPermission(PulsarAuthorizationProvider.java)。
授权提供者架构
authorizationProvider 参数指定的类就是授权逻辑的载体,默认实现是 org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider。系统在启动时会通过反射加载该类并调用 initialize,然后由 AuthorizationService.java 统一封装为对外的授权入口。如果你想对接企业内部的权限系统(如自定义 RBAC 服务),可以通过实现 AuthorizationProvider 接口并修改 authorizationProvider 配置来替换默认实现。仓库中另提供 MultiRolesTokenAuthorizationProvider(支持单 token 携带多角色)可作为参考。
使用 PulsarAdmin 编程式管理授权
除了 pulsar-admin 命令行工具,还可以通过 PulsarAdmin 客户端在代码中完成带认证的管理操作:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("http://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.build();
如需使用 TLS:
PulsarAdmin admin = PulsarAdmin.builder()
.serviceHttpUrl("https://broker:8080")
.authentication("com.org.MyAuthPluginClass", "param1:value1")
.tlsTrustCertsFilePath("/path/to/trust/cert")
.build();
authentication(...) 的第一个参数是认证插件类的全限定名,第二个参数为插件初始化参数(如 token 认证插件需要携带 JWT,格式随插件而异);启用 TLS 时需把 serviceHttpUrl 切换为 https:// 并配置 tlsTrustCertsFilePath 指向信任证书。拿到 PulsarAdmin 实例后,即可通过 admin.tenants()、admin.namespaces().grantPermissionOnNamespace(...)、admin.topics().grantPermission(...) 等 API 在程序中完成与 CLI 等价的授权管理,适合将授权流程嵌入自服务管理平台。
小结与最佳实践
Pulsar 的授权体系可以归纳为一条清晰的主线:认证确认身份 → 授权决定权限 → 权限按租户/命名空间/主题逐级细化。生产环境落地时建议遵循以下实践:
- 认证与授权必须同时启用,否则任何通过认证的客户端都能访问全部资源;
- superuser 角色保持最小化,仅授予管理员与需要跨集群互通的 broker 等系统组件;
- 优先使用"方式一"管理 proxy role 授权(每次授权同时覆盖 proxy role),避免将 proxy 设为 superuser 带来的横向移动风险;
- 按租户隔离:通过
tenants create --admin-roles为每个租户指定独立 admin role,实现多租户场景下的职责分离; - 善用命名空间级 ACL 与订阅级授权:大部分场景在命名空间粒度授权即可满足需求,敏感订阅再叠加 subscription 级白名单或
Prefix订阅模式; - 需要自定义策略时,基于
AuthorizationProvider接口扩展授权提供者,并通过authorizationProvider配置项接入。
相关配置与代码的完整位置:broker 授权参数见 conf/broker.conf,proxy 授权参数见 conf/proxy.conf,授权核心实现见 PulsarAuthorizationProvider.java 与 AuthorizationService.java,租户管理 CLI 见 CmdTenants.java,行为验证用例见 AuthorizationTest.java。