Apache Pulsar 权限管理实战：Namespace 级权限的授予、查看与撤销（pulsar-admin / REST / Java 三端详解）

发布时间：2026/9/25 6:50:01来源：尧图网络

消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载本文是一份面向 Pulsar 运维与开发人员的权限管理操作指南聚焦 Apache Pulsar 中命名空间Namespace级别权限的完整生命周期如何为指定角色role授予produce、consume等操作权限、如何查看当前已授予的权限、以及如何撤销权限。文中所有命令与代码示例均可在当前仓库对应的 Pulsar 版本2.3.0 系列文档中直接运行并结合仓库源码pulsar-client-tools、pulsar-client-admin-api、pulsar-broker、pulsar-broker-common说明其底层实现帮助读者在真实集群中正确配置授权并排查权限问题。权限模型Namespace 级与 Topic 级Pulsar 的权限体系基于角色Role与操作Action。在开启授权authorizationEnabledtrue后broker 会对每个客户端角色执行鉴权只有被授予对应操作权限的角色才能执行生产、消费或管理操作。Pulsar 支持两种粒度Namespace 级权限授予后该角色可以访问该命名空间下的所有 topic。Topic 级权限授予后该角色只能访问被授权的特定 topic。本文档site2/website-next/versioned_docs/version-2.3.0/admin-api-permissions.md重点演示 Namespace 级权限的操作Topic 级权限的授予方式可参考仓库中的 admin-api-topics.md 中关于grant-permission的章节。前置条件在 broker.conf 中开启授权在执行任何权限操作之前必须先确认 broker 已启用认证与授权。默认配置文件 conf/broker.conf第 721 行起为### --- Authentication --- ###段落中相关配置如下# Enable authentication authenticationEnabledfalse # Authentication provider name list, which is comma separated list of class names authenticationProviders # Enforce authorization authorizationEnabledfalse # Authorization provider fully qualified class-name authorizationProviderorg.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.*) authorizationAllowWildcardsMatchingfalse # 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要点说明authenticationEnabled与authorizationEnabled默认均为false即默认集群不校验身份、不强制授权。生产环境需要结合 JWT、TLS 或 Athenz 等认证插件将其打开。authorizationProvider默认使用org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider本节介绍的通配符匹配逻辑正是由该类实现的。superUserRoles中列出的角色可以执行所有管理操作并可从所有 topic 生产/消费通常用于配置管理员账号。authorizationAllowWildcardsMatching控制是否允许通配符授权默认关闭将在下文通配符授权一节详述。注意本节仅展示最常用的操作。命令、标志、参数的完整清单请查阅 reference-pulsar-admin.md。授予权限Grant permissions授予权限的本质是将一个或多个操作action授权给指定角色。支持的操作包括produce生产与consume消费在pulsar-client-tools的 CLI 实现中--actions参数还接受sources、sinks、functions、packages等管理类操作见 CmdNamespaces.java。方式一pulsar-admin CLI使用grant-permission子命令通过--actions指定操作、--role指定角色$ pulsar-admin namespaces grant-permission test-tenant/ns1 \ --actions produce,consume \ --role admin10该命令对应 CLI 命令类GrantPermissionsCmdNamespaces.java--role为必填参数指定被授权角色--actions为必填参数可传逗号分隔的操作列表最终调用getAdmin().namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions))完成授权。方式二REST API对应 HTTP 端点Pulsar admin v2 APIrole作为 URL 路径参数请求体为操作集合POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role该端点由 broker 侧 Namespaces.java 中的grantPermissionOnNamespace实现会先执行validateNamespaceName校验命名空间再调用internalGrantPermissionOnNamespace(role, actions)写入权限策略。若授权未开启接口返回501 Authorization is not enabled。方式三Java Admin APIadmin.namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions));其中grantPermissionOnNamespace定义在 Java Admin API 接口 Namespaces.java同步方法之外还提供了异步版本grantPermissionOnNamespaceAsync同文件第 657 行适合在需要非阻塞调用的场景中使用。参数actions的类型为SetAuthAction即produce/consume等枚举集合。查看权限Get permissions可以随时查看某个命名空间中各角色已被授予的权限。方式一pulsar-admin CLI使用permissions子命令并指定命名空间$ pulsar-admin namespaces permissions test-tenant/ns1 { admin10: [ produce, consume ] }输出为 JSON 格式外层键为角色名内层为操作列表。对应的 CLI 实现为Permissions命令类CmdNamespaces.java内部调用getAdmin().namespaces().getPermissions(namespace)并以 JSON 打印结果。方式二REST APIGET /admin/v2/namespaces/:tenant/:namespace/permissionsbroker 侧实现见 Namespaces.java先校验调用者具备GET_PERMISSION的命名空间操作权限然后读取命名空间的Policies返回policies.auth_policies.getNamespaceAuthentication()——这正是授权信息的持久化存储位置。方式三Java Admin APIadmin.namespaces().getPermissions(namespace);返回类型为MapString, SetAuthAction接口定义见 Namespaces.java键为角色名值为该角色在该命名空间下拥有的操作集合。撤销权限Revoke permissions撤销权限意味着指定角色将不再拥有对该命名空间的访问权。方式一pulsar-admin CLI使用revoke-permission子命令指定命名空间与--role$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \ --role admin10对应的 CLI 实现为RevokePermissions命令类CmdNamespaces.java内部调用revokePermissionsOnNamespace(namespace, role)。方式二REST APIDELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:rolebroker 侧实现见 Namespaces.java其中revokePermissionsOnNamespace会调用internalRevokePermissionsOnNamespace(role)从命名空间策略中移除该角色的全部权限记录。方式三Java Admin APIadmin.namespaces().revokePermissionsOnNamespace(namespace, role);接口定义见 Namespaces.java同样提供异步版本revokePermissionsOnNamespaceAsync同文件第 688 行。通配符授权Wildcard Authorization当broker.conf中authorizationAllowWildcardsMatchingtrue时可以通过带*通配符的角色名批量授权大幅减少需要逐条维护的权限记录。前缀匹配my.role.*$ 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等均可以生产与消费。后缀匹配*.role.my$ 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等均可以生产与消费。限制通配符仅允许出现在开头或结尾通配符匹配仅作用于角色名的开头或结尾。例如以下写法$ pulsar-admin namespaces grant-permission test-tenant/ns1 \ --actions produce,consume \ --role my.*.role此时只有字面角色my.*.role本身拥有权限角色my.1.role、my.2.role、my.foo.role、my.bar.role等不能生产与消费。底层实现原理通配符匹配逻辑由 PulsarAuthorizationProvider.java 中的checkWildcardPermission方法实现其匹配规则与上述文档描述完全一致前缀匹配当已授权角色名以*结尾时检查请求角色是否以该角色名去掉末尾*后的字符串开头即permittedRole.charAt(permittedRole.length() - 1) * checkedRole.startsWith(permittedRole.substring(0, permittedRole.length() - 1))后缀匹配当已授权角色名以*开头时检查请求角色是否以该角色名去掉开头*后的字符串结尾即permittedRole.charAt(0) * checkedRole.endsWith(permittedRole.substring(1))无论哪种匹配都要求被匹配的授权记录包含当前请求的操作permittedActions.contains(checkedAction)。在鉴权主流程中同文件第 259-301 行的allowTheSpecifiedActionOpsAsyncbroker 会先精确查找角色名对应的namespaceActions未命中时仅在conf.isAuthorizationAllowWildcardsMatching()为 true 的前提下才进入通配符匹配分支。这也解释了为什么默认配置下通配符授权不生效conf/broker.conf中该开关默认值为false。延伸权限数据如何存储从 broker 侧实现可以看到命名空间的所有授权信息都保存在该命名空间的Policies.auth_policies中getNamespaceAuthentication()返回 namespace 级角色-操作映射getTopicAuthentication()则维护 topic 级权限。每一次grant-permission/revoke-permission本质上都是通过pulsarResources.getNamespaceResources().setPoliciesAsync(...)对策略节点进行条件更新PulsarAuthorizationProvider.java这与get-permissions读取Policies的路径相互印证形成完整的写入-存储-读取-鉴权闭环。小结操作pulsar-adminREST APIadmin/v2Java Admin API授予权限namespaces grant-permission ns --actions actions --role rolePOST /admin/v2/namespaces/:tenant/:namespace/permissions/:rolegrantPermissionOnNamespace(namespace, role, actions)查看权限namespaces permissions nsGET /admin/v2/namespaces/:tenant/:namespace/permissionsgetPermissions(namespace)撤销权限namespaces revoke-permission ns --role roleDELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:rolerevokePermissionsOnNamespace(namespace, role)在实际集群中建议按以下顺序落地权限管理先通过认证插件确认角色体系再在 conf/broker.conf 中开启authorizationEnabled并配置superUserRoles随后按业务边界为命名空间逐一授予produce/consume权限若角色数量庞大且命名规范清晰可开启authorizationAllowWildcardsMatching并利用前缀/后缀通配符批量授权同时注意通配符只能出现在角色名的开头或结尾。相关主题的完整参考请继续阅读仓库中的 reference-pulsar-admin.md 与 admin-api-topics.md。赞分享消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载相关推荐CAMEL 代理体系全解析从 BaseAgent 架构到 ChatAgent 实战与源码级原理CAMEL 代理体系全解析从 BaseAgent 架构到 ChatAgent 实战与源码级原理导读本篇技术指南以 docs/key_modules/age消息队列后端流处理Apache Pulsar 命名空间级权限管理pulsar-admin、REST 与 Java 管理 API 实战指南Apache Pulsar 命名空间级权限管理pulsar admin、REST 与 Java 管理 API 实战指南 Apache Pulsar 的权限体系消息队列后端流处理Apache Pulsar 权限管理实战Namespace 级授权、通配符匹配与三种管理方式Apache Pulsar 权限管理实战Namespace 级授权、通配符匹配与三种管理方式本指南以 Apache Pulsar 官方文档《Managing消息队列后端流处理上一篇Rspack安全审计终极指南构建过程中的10个关键安全检查下一篇【亲测免费】 Apache Camel in Action 第二版实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

网站建设高端定制企业官网