Apache Pulsar 命名空间与主题权限管理实战:授权、撤销与通配符匹配详解

原创2026-09-27 17:47:282,315 阅读
文章标签:消息队列后端流处理

Apache Pulsar 命名空间与主题权限管理实战:授权、撤销与通配符匹配详解

本指南基于 Pulsar 2.4.0 管理 API,系统讲解如何在命名空间(namespace)维度为角色(role)授予、查看与撤销 produce/consume 等操作权限,并深入解析基于 authorizationAllowWildcardsMatching 的通配符授权机制及其底层实现。读完本文,你将掌握 pulsar-admin 命令行、REST API 与 Java Admin API 三种方式下的完整权限管理操作,并理解权限在 Broker 内部是如何被校验与匹配的。

权限模型:命名空间级与主题级

Pulsar 的授权体系建立在“角色 + 操作”的基础之上,权限可以挂在两个层级上:

  • 命名空间级权限:将权限授予某个角色后,该角色可以访问该命名空间下的所有主题(topic),这是日常运维中最常用的授权粒度;
  • 主题级权限:权限仅对单个主题生效,角色只能访问被明确授权的那个主题。

本文的实操章节主要围绕命名空间级权限展开;主题级权限的授予方式与命名空间级高度类似,可参考 admin-api-topics.md 中 “grant-permission” 一节。

需要说明的是,官方文档声明本页只展示最常用的操作,完整的 pulsar-admin 命令参数与 REST API 细节以对应参考手册为准,下文给出的命令与接口均可在当前仓库的源码与配置文件中找到实现依据。

前置条件:开启认证与授权

权限管理依赖 Broker 的认证(Authentication)与授权(Authorization)功能。在实际操作前,需要确认 conf/broker.conf(独立部署模式下为 conf/standalone.conf)中相关开关已开启:

  • authenticationEnabled=true:启用客户端认证;
  • authorizationEnabled=true:启用授权校验;
  • authorizationProvider:指定授权提供者,默认使用 org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider。

另外,Broker 侧有一个与本文主题直接相关的开关:

# 允许在授权中使用通配符匹配
# (通配符仅当 * 出现在角色名的第一个或最后一个位置时生效,
#   例如 *.pulsar.service、pulsar.service.*)
authorizationAllowWildcardsMatching=false

该配置项在 conf/broker.conf(第 741 行)、conf/standalone.conf(第 481 行)与 conf/websocket.conf(第 84 行)中默认均为 false。其类型为布尔值,位于 Broker 配置类 ServiceConfiguration.java 中,归属于授权(AUTHORIZATION)配置分类。启用通配符授权时,需将其显式改为 true 并重启 Broker。

授予权限(Grant Permissions)

授予权限的本质是:将一组操作(actions,如 produce、consume)授权给一个或多个指定的角色(role)。Pulsar 提供三种等价的操作入口。

方式一:pulsar-admin 命令行

使用 namespaces grant-permission 子命令,指定命名空间、--actions 与 --role 两个必选参数:

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role admin10

上述命令执行后,角色 admin10 即可在命名空间 test-tenant/ns1 下执行 produce(生产)与 consume(消费)两类操作。--actions 支持逗号分隔的多个操作,常用取值除 produce、consume 外还包括 functions、packages 等;--role 为被授权的客户端角色名。

方式二:REST API

通过 HTTP 调用命名空间权限端点:

POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role

请求体中携带要授予的操作集合,例如 <a href="https://link.gitcode.com/i/d47cfafae681790fb25ba5d308f22792" target="_blank">"produce", "consume"]。该端点在 Broker 的 [Namespaces.java 中实现,方法签名中 @PathParam 接收 tenant、namespace、role,请求体参数为 Set<AuthAction> actions。值得注意的响应状态码包括:

  • 403:当前调用者没有管理员权限;
  • 404:租户、集群或命名空间不存在;
  • 409:并发修改冲突;
  • 501:Broker 未开启授权功能(即 authorizationEnabled=false)。

方式三:Java Admin API

在 Java 代码中通过 PulsarAdmin 客户端完成相同操作:

admin.namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions));

其中 getAuthActions(actions) 将字符串操作列表转换为 Set<AuthAction> 枚举集合。对应的 grantPermissionOnNamespace 方法定义在管理 API 接口中,Broker 侧 Namespaces.java 的 REST 实现正是其服务端载体。

通配符授权:按角色模式批量授权

当 conf/broker.conf 中的 authorizationAllowWildcardsMatching 被设置为 true 后,--role 参数可以携带通配符 *,从而用一个模式匹配一批角色。需要特别强调的是:通配符只允许出现在角色名的开头或结尾。

前缀匹配(* 在开头):授予 *.role.my 后,1.role.my、2.role.my、foo.role.my、bar.role.my 等以 .role.my 结尾的角色均可生产与消费:

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role '*.role.my'

后缀匹配(* 在结尾):授予 my.role.* 后,my.role.1、my.role.2、my.role.foo、my.role.bar 等以 my.role. 开头的角色均可生产与消费:

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role 'my.role.*'

通配符在中间不生效:例如授予 my.*.role 时,只有字面角色 my.*.role 本身拥有权限,而 my.1.role、my.2.role、my.foo.role、my.bar.role 均无法生产与消费:

$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
  --actions produce,consume \
  --role 'my.*.role'

源码佐证:这一“仅前缀/后缀匹配”的语义在授权提供者 PulsarAuthorizationProvider.java 的 checkWildcardPermission 方法中有精确实现——当被授权角色名的最后一个字符是 * 时,执行 checkedRole.startsWith(...) 前缀匹配;当第一个字符是 * 时,执行 checkedRole.endsWith(...) 后缀匹配;* 位于中间的角色名不会进入通配分支。同时,只有 authorizationAllowWildcardsMatching 为 true 时,命名空间权限(L279-L282)与主题权限(L440-L449)的校验路径才会启用通配匹配。

查看权限(Get Permissions)

查看权限用于确认某个命名空间下哪些角色被授予了哪些操作。

方式一:pulsar-admin 命令行

$ pulsar-admin namespaces permissions test-tenant/ns1
{
  "admin10": [
    "produce",
    "consume"
  ]
}

输出为一个 JSON 映射:键为角色名,值为该角色拥有的操作列表。该命令定义于 CmdNamespaces.java 中,对应命令描述为 “Get the permissions on a namespace”。

方式二:REST API

GET /admin/v2/namespaces/:tenant/:namespace/permissions

Broker 侧对应 Namespaces.java 的 getPermissions 方法:先校验命名空间是否存在,再校验调用者是否具备 GET_PERMISSION 操作权限,最后返回 Policies.auth_policies.getNamespaceAuthentication(),即该命名空间的认证策略中记录的“角色 → 操作集合”映射。

方式三:Java Admin API

admin.namespaces().getPermissions(namespace);

返回类型为 Map<String, Set<AuthAction>>,与 REST 响应结构一一对应。

撤销权限(Revoke Permissions)

撤销权限后,被撤销的角色将不再拥有对该命名空间的访问能力。

方式一:pulsar-admin 命令行

$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
  --role admin10

--role 为必选参数,指定要移除权限的角色。

方式二:REST API

DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role

Broker 侧 Namespaces.java 的 revokePermissionsOnNamespace 方法完成该操作,成功返回后角色在该命名空间下的全部权限(包括所有操作类型)均被清除。

方式三:Java Admin API

admin.namespaces().revokePermissionsOnNamespace(namespace, role);

底层实现:一条权限操作如何贯穿 Broker

将三种操作入口放在一起观察,可以看到清晰的调用链结构:

  1. 客户端入口:pulsar-admin 命令行工具解析参数后调用 Java Admin API;REST 请求则直接命中 Broker 的 Jersey 端点。
  2. Broker 控制面:命名空间权限的 HTTP 端点统一收敛在 Namespaces.java 的 getPermissions / grantPermissionOnNamespace / revokePermissionsOnNamespace 三个方法上,其中授予与撤销操作分别委托给 internalGrantPermissionOnNamespace / internalRevokePermissionsOnNamespace,最终将变更写入命名空间的策略(Policies)存储。
  3. 数据面校验:客户端实际生产/消费消息时,授权提供者 PulsarAuthorizationProvider.java 会读取命名空间与主题的策略,按“角色精确匹配优先,通配匹配兜底”的顺序判定该角色是否被允许执行目标操作。
  4. 配置开关:是否启用通配匹配由 ServiceConfiguration.java 中的 authorizationAllowWildcardsMatching 字段控制,默认关闭,需要在 conf/broker.conf 等配置文件中显式开启。

值得一提的是,Broker 还提供了订阅级权限(subscription permission)的独立管理接口,例如 grantPermissionOnSubscription、getPermissionOnSubscription(见 Namespaces.java),用于限制角色对特定订阅的访问,可在更精细的权限场景下按需使用。

小结

  • 命名空间级权限让角色获得该命名空间下所有主题的访问权;主题级权限则精确到单个主题,二者可以叠加生效。
  • 授权、查看、撤销三种操作在 pulsar-admin、REST API、Java Admin API 三套入口间完全等价,可按团队技术栈任选其一。
  • 通配符授权必须显式开启 authorizationAllowWildcardsMatching=true,且 * 仅支持位于角色名首尾的前缀/后缀匹配,中间位置的通配符不会被特殊处理。
  • 权限校验的最终落脚点是命名空间策略中的认证映射(auth_policies),所有变更都会持久化并在 Broker 数据面读写时实时生效。
登录后查看全文
pulsar