Apache Pulsar 授权与 ACL 配置实战:Broker/Proxy 授权、代理角色与租户权限管理

原创2026-09-23 15:05:551,982 阅读
文章标签:消息队列后端流处理

Apache Pulsar 授权与 ACL 配置实战:Broker/Proxy 授权、代理角色与租户权限管理

Apache Pulsar 的授权(Authorization)机制在完成客户端身份认证之后,进一步回答"该客户端能做什么"的问题:它决定一个持有角色令牌(role token)的客户端能否创建租户、能否对某个命名空间或主题执行生产(produce)、消费(consume)等操作。本文以 site2/website-next/versioned_docs/version-2.1.1-incubating/security-authorization.md 为主线,结合本仓库中的 conf/broker.conf、conf/proxy.conf 以及授权相关的源码实现,系统讲解如何在 Broker 与 Proxy 上启用授权、如何配置超级用户(superuser)与代理角色(proxy roles)、如何通过 pulsar-admin 管理租户与权限,并给出 PulsarAdmin 客户端启用认证的 Java 代码示例。读完本文,你将能够为 Pulsar 集群搭建一套从"认证"到"授权"的完整访问控制方案。

授权在 Pulsar 安全体系中的位置

Pulsar 的安全体系分为两层:认证(Authentication)与授权(Authorization)。

  • 认证:由认证提供方负责识别客户端身份,并把客户端与一个角色令牌(role token)关联起来。角色是一个字符串,例如 admin 或 app1,可以代表单个或多个客户端。目前 Pulsar 支持 TLS、Athenz、Kerberos、JWT 等认证提供方。
  • 授权:如果只启用认证,那么任何通过认证的角色令牌都能访问集群中的所有资源。授权才是决定"客户端能做什么"的过程。

权限最高的角色令牌被称为超级用户(superuser)。超级用户可以创建和销毁租户(tenant),并且拥有对所有租户资源的完全访问权限。

当超级用户创建一个租户时,该租户会被分配一个管理员角色(admin role)。持有管理员角色令牌的客户端可以创建、修改和销毁命名空间(namespace),也可以把权限授予或撤销给该命名空间下的其他角色令牌。

从源码看,授权的能力边界由 AuthorizationProvider.java 接口定义,它提供了 isSuperUser、isTenantAdmin、canProduceAsync、canConsumeAsync 等核心方法;默认实现为 org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider(见 conf/broker.conf 中 authorizationProvider 配置项)。此外还有支持多角色令牌的 MultiRolesTokenAuthorizationProvider 等扩展实现。这意味着授权行为是可插拔的,你可以在不改动 Broker 主流程的前提下替换授权策略。

Broker 与 Proxy 授权配置

启用授权并指定超级用户

授权能力默认是关闭的。你可以在 Broker 的配置文件(conf/broker.conf)中启用授权并指定超级用户角色:

authorizationEnabled=true
superUserRoles=my-super-user-1,my-super-user-2

conf/broker.conf 中对应的完整配置段(约 721–745 行)如下,它同时也给出了相关参数的默认值:

### --- Authentication --- ###

# Enable authentication
authenticationEnabled=false

# Authentication provider name list, which is comma separated list of class names
authenticationProviders=

# Interval of time for checking for expired authentication credentials
authenticationRefreshCheckSeconds=60

# Enforce authorization
authorizationEnabled=false

# Authorization provider fully qualified class-name
authorizationProvider=org.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.*)
authorizationAllowWildcardsMatching=false

# 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=

几个关键参数的含义:

参数 默认值 说明
authorizationEnabled false 是否在 Broker 上强制执行授权检查
authorizationProvider org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider 授权提供方的全限定类名,用于自定义授权逻辑
superUserRoles 空 被视为超级用户的角色列表,逗号分隔;这些角色可以执行所有管理操作,并在所有主题上生产/消费
authorizationAllowWildcardsMatching false 是否允许角色名通配符匹配(通配符 * 只能出现在角色名的开头或结尾,例如 *.pulsar.service)
authenticationRefreshCheckSeconds 60 检查认证凭证过期状态的间隔时间,过期后 Broker 会强制重新认证

在 AuthorizationProvider.java 中,isSuperUser 的默认实现正是把角色与 ServiceConfiguration.getSuperUserRoles() 集合比对:只要 role != null && superUserRoles.contains(role) 即视为超级用户。因此 superUserRoles 是决定"谁拥有集群最高权限"的直接依据,务必只授予受信任的身份。

完整的参数列表见 conf/broker.conf 文件,各参数的默认值也可参考 reference-configuration.md 中的 Broker 配置章节。

典型的超级用户使用场景包括:管理员账号、客户端,以及 Broker 与 Broker 之间的授权。当启用地理复制(geo-replication)时,每个 Broker 都需要能向其他集群的所有主题发布消息,因此复制链路涉及的角色需要具备相应权限。

在 Proxy 上启用授权

你也可以在 Proxy 配置文件(conf/proxy.conf)中启用授权。一旦在 Proxy 上启用授权,Proxy 会在把请求转发给 Broker 之前额外执行一次授权检查;而如果 Broker 上也启用了授权,Broker 收到转发过来的请求时还会再检查一次请求的授权。因此形成了"Proxy 前置检查 + Broker 二次检查"的双层防线。

conf/proxy.conf 中与授权相关的配置段(约 132–146 行):

### ---Authorization --- ###

# Role names that are treated as "super-users," meaning that they will be able to perform all admin
# operations and publish/consume to/from all topics (as a comma-separated list)
superUserRoles=

# 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 forwared 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 中配置的角色(参见 security-tls-authentication.md 中关于 TLS 认证下为 Proxy 配置客户端密钥对并把其角色放入 proxyRoles 的说明)。然而,用户通过 Proxy 连接到集群时,并不希望自己以 Proxy 的身份被识别——他们期望以自己在 Proxy 处完成认证时所用的角色与集群交互。

Pulsar 通过 Proxy roles(代理角色) 机制来解决这个问题。Proxy roles 在 Broker 配置文件(conf/broker.conf)中指定。规则如下:

  • 如果一个与 Broker 完成认证的客户端,其角色是 proxyRoles 中的某一个,那么该客户端发出的所有请求都必须额外携带它在 Proxy 处认证得到的客户端角色信息;
  • 这个信息被称为原始主体(original principal);
  • 如果请求中缺少原始主体,那么该客户端无法访问任何资源。

conf/broker.conf 中对应的配置(约 591–594 行):

### --- Authentication --- ###
# Role names that are treated as "proxy roles". If the broker sees a request with
# role as proxyRoles - it will demand to see a valid original principal.
proxyRoles=

与之配套的还有 authenticateOriginalAuthData 参数:若置为 true,Broker 会认证请求中携带的原始认证数据;否则仅接受并(按需)授权 originalPrincipal。

授权 Proxy 角色与原始主体的两种策略

要让资源能够通过 Proxy 被访问,Proxy 角色(proxy role)和原始主体(original principal)两者都必须被授权。管理员可以采取两种策略:

策略一:为每个资源显式授权 Proxy 角色(更安全)

每次授予资源访问权时,同时把 Proxy 角色一并授予。例如,假设 Proxy 角色名为 proxy1:

  • 当超级用户创建租户时,把 proxy1 指定为该租户的管理员角色之一;
  • 当某个角色被授予在某个命名空间上生产或消费的权限时,如果该客户端希望通过 Proxy 生产或消费,则需要给 proxy1 授予相同的权限。

策略二:把 Proxy 角色设为超级用户(更简单但有风险)

把 Proxy 角色加入 superUserRoles,使 Proxy 可以访问所有资源。客户端仍然需要在 Proxy 处完成认证,而且所有经由 Proxy 发出的请求,其角色都会被"降级"为已认证客户端的原始主体。风险在于:如果 Proxy 被攻破,攻击者就能获得集群的完全访问权限。

配置示例(conf/broker.conf):

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

源码层面的校验逻辑

原始主体与代理角色的合法性校验实现在 AuthorizationService.java 的 isValidOriginalPrincipal 方法中,其核心规则与文档描述完全一致:

  1. 如果 authenticatedPrincipal 在 proxyRoles 中,则必须提供 originalPrincipal,否则校验失败,报错 "originalPrincipal must be provided when connecting with a proxy role.";
  2. 如果 originalPrincipal 本身也在 proxyRoles 中,则校验失败,报错 "originalPrincipal cannot be a proxy role.";
  3. 非 Proxy 角色携带 originalPrincipal 时(且两者不相等)会记录警告日志,提示该行为在未来的版本中不再被允许。

在 ServerCnx.java 中,originalPrincipal 作为连接级字段维护(第 194 行),并在认证握手时从 ConnectCommand 中提取(第 882–892 行)。Broker 在后续所有授权检查(如生产、消费、命名空间操作)中都会同时考量 authRole 与 originalPrincipal——例如 ServerCnx.java 中同时校验 isSuperUser(originalPrincipal, ...) 与 isSuperUser(authRole, ...) 两个结果。这意味着即使连接方是超级用户 Proxy,请求实际生效的权限仍然取决于其携带的原始主体。

管理租户(Administer Tenants)

Pulsar 的租户(tenant)是一个用于分配容量、实施认证/授权方案的管理单元。租户通常由 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 角色通过认证的客户端,被允许在该租户上执行所有管理任务。

命令的实现位于 CmdTenants.java:create 子命令解析 --admin-roles(-r)与 --allowed-clusters 参数,构造 TenantInfoImpl(adminRoles 与 allowedClusters 集合)后调用 getAdmin().tenants().createTenant(tenant, tenantInfo)。其背后对应管理 API 的 POST /admin/v2/tenants/:tenant 接口,以及 Java 管理 API 的 admin.tenants().createTenant(tenantName, tenantInfo)(详见 admin-api-tenants.md)。

补充说明:

  • --admin-roles 支持逗号分隔的多个角色,例如 --admin-roles role1,role2,role3;
  • 如果省略 --allowed-clusters,从源码(CmdTenants.java)可以看到,命令会回退为当前集群列表中所有可用集群;
  • 租户的 adminRoles 直接决定了 AuthorizationProvider.isTenantAdmin 的判定结果——见 AuthorizationProvider.java,它检查 tenantInfo.getAdminRoles().contains(role)。

主题名称的层级结构

Pulsar 主题名称的结构反映了租户、集群、命名空间之间的层级关系:

persistent://tenant/namespace/topic
  • tenant:租户,是容量分配与认证/授权方案的实施单元;
  • namespace:命名空间,一组属于同一租户的主题的虚拟分组,也是权限授予的基本粒度之一;
  • topic:主题,消息生产与消费的实际载体。

因此,授权模型天然是分层的:租户管理员 > 命名空间权限 > 主题权限。

管理权限(Manage Permissions)

权限的授予、查询与撤销可以使用 Pulsar 的管理工具完成,详见 admin-api-permissions.md。Pulsar 支持两种粒度的授权:

  • 命名空间级权限:授予后,用户可访问该命名空间下的所有主题;
  • 主题级权限:授予后,用户只能访问该主题。

以下为命名空间级权限的常用操作示例:

授予权限(produce 与 consume):

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

对应 REST API 为 POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role,Java API 为 admin.namespaces().grantPermissionOnNamespace(namespace, role, authActions)。

查看权限:

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

对应 REST API 为 GET /admin/v2/namespaces/:tenant/:namespace/permissions,Java API 为 admin.namespaces().getPermissions(namespace)。

撤销权限:

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

对应 REST API 为 DELETE /admin/v2/namespaces/:tenant/:namespace/permissions/:role,Java API 为 admin.namespaces().revokePermissionsOnNamespace(namespace, role)。

角色名通配符:当 conf/broker.conf 中的 authorizationAllowWildcardsMatching=true 时,可以使用通配符 * 进行批量授权。通配符只能出现在角色名的开头或结尾:

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

上述命令使 my.role.1、my.role.2、my.role.foo 等角色都可以生产与消费。类似地,*.role.my 可匹配 1.role.my、foo.role.my 等。但中间通配符不生效——例如 my.*.role 只匹配字面角色 my.*.role,而 my.1.role 等无法获得权限。

Pulsar Admin 客户端认证

管理 API 的调用方(例如自动化运维脚本或管理平台)同样需要携带认证信息。PulsarAdmin 客户端通过 authentication 方法指定认证插件类及参数:

PulsarAdmin admin = PulsarAdmin.builder()
                    .serviceHttpUrl("http://broker:8080")
                    .authentication("com.org.MyAuthPluginClass", "param1:value1")
                    .build();

如果需要使用 TLS 加密管理通道,则在 builder 中额外配置信任证书路径,并把服务地址切换为 HTTPS:

PulsarAdmin admin = PulsarAdmin.builder()
                    .serviceHttpUrl("https://broker:8080")
                    .authentication("com.org.MyAuthPluginClass", "param1:value1")
                    .tlsTrustCertsFilePath("/path/to/trust/cert")
                    .build();

其中:

  • serviceHttpUrl:Broker 的 HTTP 管理服务地址(http 或 https 取决于是否启用 TLS);
  • authentication:第一个参数是认证插件类的全限定名(如 org.apache.pulsar.client.impl.auth.AuthenticationTls),第二个参数是插件参数(param1:value1 形式的键值对,例如 tlsCertFile:...,tlsKeyFile:...);
  • tlsTrustCertsFilePath:TLS 模式下用于校验服务端证书的信任证书路径。

完整配置清单与检查要点

要在集群中落地一套授权方案,建议按以下顺序检查:

  1. Broker 配置(conf/broker.conf):确认 authenticationEnabled=true、authenticationProviders 已填写,然后设置 authorizationEnabled=true、superUserRoles、proxyRoles(若存在 Proxy 部署);
  2. Proxy 配置(conf/proxy.conf):确认 authenticationEnabled=true,并按需设置 authorizationEnabled=true、superUserRoles、forwardAuthorizationCredentials;
  3. 授权提供方:默认使用 org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider,如需多角色令牌等能力可替换为 MultiRolesTokenAuthorizationProvider 等实现,或基于 AuthorizationProvider.java 接口自行扩展;
  4. 租户与权限:使用 bin/pulsar-admin tenants create 创建租户并分配 --admin-roles,再通过 namespaces grant-permission/revoke-permission/permissions 管理命名空间级权限;
  5. 客户端侧:生产/消费客户端携带各自角色对应的认证凭证;管理类调用方使用 PulsarAdmin.builder().authentication(...) 配置认证插件。

需要注意的边界条件:授权依赖认证先行,未启用认证时角色令牌无从谈起;superUserRoles 中的角色拥有全集群最高权限,应严格限定在受信任的管理员、运维组件与 Broker 间复制链路使用;把 Proxy 角色加入 superUserRoles 虽然便捷,但会显著放大 Proxy 被攻破时的风险,应优先采用"逐资源显式授权 Proxy 角色"的方式。

登录后查看全文
pulsar