Apache Pulsar 权限管理实战:Namespace 级授权、通配符匹配与三种管理方式

原创2026-09-23 14:54:531,336 阅读
文章标签:消息队列后端流处理

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(即未启用授权)时抛出 HTTP 501 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 通配符的前缀/后缀匹配实现。实际部署中,建议先开启认证与授权,再按"角色 + 动作"的最小粒度进行授权,必要时利用通配符简化大规模角色管理。

登录后查看全文
pulsar