Apache Pulsar 权限管理实战:Namespace 级授权、通配符匹配与三种管理方式
Apache Pulsar 权限管理实战:Namespace 级授权、通配符匹配与三种管理方式
本指南以 Apache Pulsar 官方文档《Managing permissions》为主体,系统讲解 Pulsar 基于 Role(角色) 的命名空间级(namespace-level)权限管理机制:如何通过 pulsar-admin 命令行、REST API 与 Java Admin API 三种方式完成权限的授予(grant)、查询(get)与撤销(revoke),并深入剖析 authorizationAllowWildcardsMatching 通配符授权的匹配规则与底层源码实现。读完本文,你将掌握为多租户环境下的用户/角色精确配置 produce、consume 等操作权限的完整实战方案。
重要说明:本文对应的官方文档页只展示最常用的操作。有关
pulsar-admin的完整命令、flags 与描述,以及 REST API、Java Admin API 的完整参数与响应示例,请以仓库内相关 API 源码与后续版本官方文档为准。
一、Pulsar 权限模型:Namespace 级与 Topic 级
Pulsar 的授权体系建立在"认证(Authentication)+ 授权(Authorization)"两层之上:认证确定"你是谁"(即解析出 Role),授权决定"你能做什么"(即允许哪些操作)。Pulsar 允许以 namespace 维度或 topic 维度为角色授予权限:
- Namespace 级权限:授予后,该用户可以访问该 namespace 下的所有 topic;
- Topic 级权限:授予后,该用户只能访问被授权的那个 topic。
从源码看,这两类权限分别存放在不同的数据结构中。在 AuthPoliciesImpl.java 中可以看到:
private Map<String, Set<AuthAction>> namespaceAuthentication = new TreeMap<>();
private Map<String, Map<String, Set<AuthAction>>> topicAuthentication = new TreeMap<>();
即 namespace 级权限直接以 role -> Set<AuthAction> 映射存储,而 topic 级权限则是 topic -> (role -> Set<AuthAction>) 的两层映射。本文档主体聚焦 namespace 级权限;topic 级权限的授予方法参见 manage topics 文档(主题为 Grant permission 一节)。
权限操作(AuthAction)有哪些
在 AuthAction.java 中定义了完整的授权动作枚举:
public enum AuthAction {
produce, // 发布消息的权限
consume, // 消费消息的权限
functions, // Functions 操作权限
sources, // Sources 操作权限
sinks, // Sinks 操作权限
packages // Packages 操作权限
}
因此 pulsar-admin 的 --actions 参数可接受的取值即为:produce,consume,sources,sinks,functions,packages(可组合、逗号分隔),与 CLI 源码 CmdNamespaces.java 中的描述一致。CLI 层会通过 CliCommand.getAuthActions() 将字符串逐个 AuthAction.valueOf(action) 转换为枚举集合,若传入非法动作会直接报错并列出所有可选值。
二、前置条件:启用认证与授权
权限管理真正生效的前提是 Broker 开启了授权。在 conf/broker.conf 中,与本主题直接相关的配置项如下:
| 配置项 | 默认值 | 说明 |
|---|---|---|
authenticationEnabled |
false |
是否启用认证,启用后才能解析出客户端 Role |
authenticationProviders |
(空) | 认证提供方类名列表(逗号分隔),如 org.apache.pulsar.broker.authentication.AuthenticationProviderToken |
authorizationEnabled |
false |
是否启用授权,必须设为 true 权限才会被强制校验 |
authorizationProvider |
org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider |
授权提供方实现类 |
authorizationAllowWildcardsMatching |
false |
是否允许角色名通配符匹配(见下文第三节) |
superUserRoles |
(空) | 超级用户角色列表,可执行所有 admin 操作及任意 topic 的发布/消费 |
anonymousUserRole |
(空) | 未认证用户所扮演的匿名角色 |
其中 authorizationAllowWildcardsMatching 在源码 ServiceConfiguration.java 中的定义与 broker.conf 注释完全对应:通配符 * 仅可出现在角色名的首部或尾部(如 *.pulsar.service、pulsar.service.*)。
若授权未启用,权限授予接口将无法工作。在 NamespacesBase.java 中,
internalGrantPermissionOnNamespace会先获取AuthorizationService,当其为null(即未启用授权)时抛出 HTTP501 NOT_IMPLEMENTED("Authorization is not enabled")。
三、授予权限(Grant permissions)
可以为特定角色授予一组操作权限(如 produce、consume)。以下分别给出三种管理方式的完整用法。
方式一:pulsar-admin 命令行
使用 grant-permission 子命令,通过 --actions 指定动作、--role 指定角色:
$ pulsar-admin namespaces grant-permission test-tenant/ns1 \
--actions produce,consume \
--role admin10
执行后,角色 admin10 即可在 test-tenant/ns1 命名空间下发布并消费消息。
方式二:REST API
发送 HTTP POST 请求到 Namespace 权限端点:
POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role
请求体为要授予的动作集合。对应 Broker 端处理入口位于 Namespaces.java 的 grantPermissionOnNamespace 方法,其 @Path 注解与上述 URL 完全一致:
@POST
@Path("/{tenant}/{namespace}/permissions/{role}")
@ApiOperation(value = "Grant a new permission to a role on a namespace.")
public void grantPermissionOnNamespace(@PathParam("tenant") String tenant,
@PathParam("namespace") String namespace, @PathParam("role") String role,
@ApiParam(value = "List of permissions for the specified role") Set<AuthAction> actions) {
validateNamespaceName(tenant, namespace);
internalGrantPermissionOnNamespace(role, actions);
}
注意该接口可能的响应码:403(无 admin 权限)、404(tenant/namespace 不存在)、409(并发修改冲突)、501(授权未启用)。
方式三:Java Admin API
admin.namespaces().grantPermissionOnNamespace(namespace, role, getAuthActions(actions));
其中 getAuthActions(actions) 将字符串集合转换为 Set<AuthAction>。更完整的调用形式(显式构造 AuthAction 集合):
admin.namespaces().grantPermissionOnNamespace(
"test-tenant/ns1",
"admin10",
Sets.newHashSet(AuthAction.produce, AuthAction.consume)
);
底层实现:权限如何持久化
从源码链路看,CLI 与 REST API 最终都会汇聚到 NamespacesBase.internalGrantPermissionOnNamespace():
protected void internalGrantPermissionOnNamespace(String role, Set<AuthAction> actions) {
validateNamespaceOperation(namespaceName, NamespaceOperation.GRANT_PERMISSION);
checkNotNull(role, "Role should not be null");
checkNotNull(actions, "Actions should not be null");
try {
AuthorizationService authService = pulsar().getBrokerService().getAuthorizationService();
if (null != authService) {
authService.grantPermissionAsync(namespaceName, actions, role, null).get();
} else {
throw new RestException(Status.NOT_IMPLEMENTED, "Authorization is not enabled");
}
} catch (InterruptedException e) {
// ... 记录日志并抛出 RestException
} catch (ExecutionException e) {
// NotFoundException -> 404 "Namespace does not exist"
// BadVersionException / IllegalStateException -> 409 "Concurrent modification"
}
}
这里可以看到:授予权限本质上是调用 AuthorizationService.grantPermissionAsync() 将角色与动作写入 namespace 的 Policies(策略元数据)并异步等待完成,整个过程通过版本号校验避免并发写冲突,冲突时返回 409。
四、通配符授权:authorizationAllowWildcardsMatching 详解
当 broker.conf 中 authorizationAllowWildcardsMatching=true 时,可以对角色名进行通配符授权。其规则要点:
- 通配符
*只能出现在角色名的开头或结尾; - 匹配发生在授予阶段之前:只需为模式角色(如
my.role.*)授予权限,所有符合该模式的实际角色即可共享该权限。
前缀通配(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 等角色均可执行 produce / consume。
后缀通配(*.role)
$ 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 等角色均可执行 produce / consume。
限制:中间通配无效
注意:通配符匹配仅作用于角色名的开头或结尾。例如:
$ 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 等角色无法执行 produce / consume。
源码级验证:前缀/后缀匹配实现
上述行为与 PulsarAuthorizationProvider.checkWildcardPermission() 的实现完全对应:
private boolean checkWildcardPermission(String checkedRole, AuthAction checkedAction,
Map<String, Set<AuthAction>> permissionMap) {
for (Map.Entry<String, Set<AuthAction>> permissionData : permissionMap.entrySet()) {
String permittedRole = permissionData.getKey();
Set<AuthAction> permittedActions = permissionData.getValue();
// Prefix match:permittedRole 以 * 结尾,检查 checkedRole 是否以前缀开头
if (checkedRole != null) {
if (permittedRole.charAt(permittedRole.length() - 1) == '*'
&& checkedRole.startsWith(permittedRole.substring(0, permittedRole.length() - 1))
&& permittedActions.contains(checkedAction)) {
return true;
}
// Suffix match:permittedRole 以 * 开头,检查 checkedRole 是否以后缀结尾
if (permittedRole.charAt(0) == '*' && checkedRole.endsWith(permittedRole.substring(1))
&& permittedActions.contains(checkedAction)) {
return true;
}
}
}
return false;
}
可以看到匹配逻辑只检查两种情况:以 * 结尾做前缀匹配(startsWith)、以 * 开头做后缀匹配(endsWith),这正是"通配符只能出现在开头或结尾"的代码根因。同时,通配符匹配只在 authorizationAllowWildcardsMatching 开启时才会被触发(见 PulsarAuthorizationProvider.java 与 #L440-L449 处的 if (conf.isAuthorizationAllowWildcardsMatching()) 分支),且在实际授权判定时,通配符匹配要求该角色名模式恰好拥有对应的 action(permittedActions.contains(checkedAction))。
五、查询权限(Get permissions)
可以查看某个 namespace 下各角色已被授予的权限。
方式一:pulsar-admin 命令行
使用 permissions 子命令,指定 namespace:
$ pulsar-admin namespaces permissions test-tenant/ns1
{
"admin10": [
"produce",
"consume"
]
}
输出为 JSON 格式的角色 -> 动作列表映射。
方式二:REST API
GET /admin/v2/namespaces/:tenant/:namespace/permissions
响应体即为 Map<String, Set<AuthAction>>(如上面的 JSON 所示)。对应 Broker 端实现位于 Namespaces.java:
@GET
@Path("/{tenant}/{namespace}/permissions")
public Map<String, Set<AuthAction>> getPermissions(@PathParam("tenant") String tenant,
@PathParam("namespace") String namespace) {
validateNamespaceName(tenant, namespace);
validateNamespaceOperation(NamespaceName.get(tenant, namespace), NamespaceOperation.GET_PERMISSION);
Policies policies = getNamespacePolicies(namespaceName);
return policies.auth_policies.getNamespaceAuthentication();
}
可见查询本质是读取 namespace 的 Policies 元数据并返回其中的 auth_policies.namespaceAuthentication 映射。可能的响应码:403(无 admin 权限)、404(tenant/namespace 不存在)。
方式三:Java Admin API
admin.namespaces().getPermissions(namespace);
返回类型为 Map<String, Set<AuthAction>>,可直接迭代输出:
Map<String, Set<AuthAction>> perms = admin.namespaces().getPermissions("test-tenant/ns1");
perms.forEach((role, actions) -> System.out.println(role + " -> " + actions));
六、撤销权限(Revoke permissions)
撤销权限意味着相关角色不再拥有该 namespace 的访问权限。
方式一:pulsar-admin 命令行
使用 revoke-permission 子命令,指定 namespace 与 --role:
$ pulsar-admin namespaces revoke-permission test-tenant/ns1 \
--role admin10
方式二:REST API
DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role
对应 Broker 端实现位于 Namespaces.java,内部调用 internalRevokePermissionsOnNamespace(role)。
方式三:Java Admin API
admin.namespaces().revokePermissionsOnNamespace(namespace, role);
底层实现:从 Policies 中移除角色
与授予流程不同,撤销操作直接在 NamespacesBase.internalRevokePermissionsOnNamespace() 中通过更新 Policies 完成:
protected void internalRevokePermissionsOnNamespace(String role) {
validateNamespaceOperation(namespaceName, NamespaceOperation.REVOKE_PERMISSION);
validatePoliciesReadOnlyAccess();
checkNotNull(role, "Role should not be null");
updatePolicies(namespaceName, policies -> {
policies.auth_policies.getNamespaceAuthentication().remove(role);
return policies;
});
}
可以看到:撤销即从 namespace 的 auth_policies 中 移除该角色的键值(remove(role)),并以 CAS 方式写回元数据存储。同时它会先调用 validatePoliciesReadOnlyAccess(),若 namespace 策略处于只读模式则拒绝写入。
七、常见场景与注意事项
- 命名空间即租户隔离单元:在多租户场景中,通常先为每个团队划分 namespace,再按角色授予
produce/consume权限,实现最小权限原则。 - 动作粒度:
--actions支持produce,consume,sources,sinks,functions,packages六种;不同的操作(如 Functions/Sources/Sinks)需要对应的独立授权动作。 - 通配符的使用边界:
authorizationAllowWildcardsMatching默认为false;开启后仍需注意通配符只能位于角色名首/尾,且中间通配(如my.*.role)不会被特殊处理,只会按字面角色名匹配。 - 超级用户:
superUserRoles中列出的角色拥有全部 admin 操作与任意 topic 的发布/消费能力,无需逐一授权。 - 错误排查:授予/撤销时若收到
501,说明authorizationEnabled=false,需先启用授权;收到409说明存在并发修改;收到404说明目标 namespace 或角色不存在。
结语
本文基于 Apache Pulsar 官方《Managing permissions》文档,完整覆盖了 namespace 级权限的授予、查询、撤销三种管理方式,并结合仓库源码剖析了 AuthAction 枚举、REST 端点、Policies 持久化及 authorizationAllowWildcardsMatching 通配符的前缀/后缀匹配实现。实际部署中,建议先开启认证与授权,再按"角色 + 动作"的最小粒度进行授权,必要时利用通配符简化大规模角色管理。