企业官网建设流程全解析

• 消息队列
• 后端
• 流处理

本文以 Pulsar 官方文档《Token authentication admin》（security-token-admin.md）为主线，系统讲解基于 JWT（RFC-7519）的 Token 认证在 Pulsar 中的完整落地流程：从密钥对/对称密钥的生成、带 subject 与过期时间的 Token 签发、命名空间授权，到 Broker 与 Proxy 两侧的认证配置。读完本文，你可以独立完成一套生产可用的 Token 认证体系配置，并从源码层面理解 Pulsar 是如何解析、校验 Token 的。

1. Token 认证概述：Principal 与 JWT

Pulsar 支持使用基于 JSON Web Tokens（RFC-7519）的安全令牌来认证客户端。Token 的作用是把 Pulsar 客户端与某个"principal"（也叫 "role"，角色）关联起来，之后授权引擎再根据这个角色授予相应的操作权限（例如：向某个 topic 发布消息或从某个 topic 消费）。

用户（或角色）通常会从管理员或某个自动化服务处获得一段 token 字符串。一个签名 JWT 的紧凑表示形如：

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY

创建客户端实例时，应用可以直接指定 token 字符串；也可以传入一个"token supplier"——即一个在客户端库需要 token 时返回 token 的函数，这种方式便于在 token 过期时自动刷新。Java 客户端侧对应实现见 AuthenticationToken，它同时支持Supplier<String>形式的动态供应（第 49~55 行）。

安全提示：务必启用 TLS 传输加密发送 token 等价于在网络上发送密码。与 Pulsar 服务通信时强烈建议始终启用 TLS 加密传输（参见文档体系中的 "Transport Encryption using TLS" 主题，对应文档 security-tls-transport）。

2. 密钥体系：Secret Key 与 Public/Private Key

JWT 支持两类密钥来生成和校验 Token：

• 对称（Symmetric）：只有一把Secret密钥，既用于生成 Token，也用于校验 Token；
• 非对称（Asymmetric）：一对密钥。
  • Private（私钥）用于生成 Token；
  • Public（公钥）用于校验 Token。

2.1 创建 Secret Key

使用对称密钥时，管理员创建密钥并用它生成客户端 Token；同一把密钥还会配置到各 Broker 上，使 Broker 能够校验客户端。

输出文件默认生成在 Pulsar 安装目录的根目录下，也可以为输出文件指定绝对路径。

$ bin/pulsar tokens create-secret-key --output my-secret.key

如果需要生成 base64 编码的密钥文件：

$ bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64

从 TokensCliUtils 中的CommandCreateSecretKey（第 58~86 行）可以看到该命令的完整参数集：

• -a, --signature-algorithm：签名算法，默认 HS256；
• -o, --output：把密钥写入文件而非 stdout；
• -b, --base64：对密钥做 base64 编码（默认 false，即原始二进制 DER 编码直接写文件）。

底层生成逻辑委托给 AuthTokenUtils 的createSecretKey()（第 48~50 行），由 jjwt 库的Keys.secretKeyFor(algorithm)完成。

2.2 创建 Public/Private 密钥对

使用非对称体系时需要创建一对密钥。Pulsar 支持 jjwt 库所支持的全部签名算法（HS256/RS256/ES256 等，可通过--signature-algorithm指定）。

输出文件默认生成在 Pulsar 安装目录的根目录下，也可以为输出文件指定绝对路径。

$ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key

• my-private.key应存放在安全位置，仅由管理员用于生成新 Token；
• my-public.key需要分发到所有 Pulsar Broker。公钥可以公开共享，不会带来安全问题。

源码层面，CommandCreateKeyPair（TokensCliUtils 第 88~107 行）默认使用RS256算法，两个输出文件均为必填参数。这里有一个容易踩坑的细节：--output-*写出的是key.getEncoded()原始字节，即 DER 编码（公钥为 X.509/SubjectPublicKeyInfo 格式，私钥为 PKCS8 格式）。校验端也严格按此解码：AuthTokenUtils 的decodePrivateKey使用PKCS8EncodedKeySpec，decodePublicKey使用X509EncodedKeySpec。这就是官方文档强调"key files must be DER-encoded"的源码依据——PEM 格式（Base64 文本包裹）的密钥文件无法被 Broker 直接读取。

3. 生成 Token

Token 是与用户（角色）绑定的凭据，绑定关系通过 "principal"/"role" 完成。对于 JWT Token，这个字段通常称为subject（subject 与 principal 是完全相同的概念）。生成的 Token必须设置 subject 字段。

使用对称密钥签发：

$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --subject test-user

执行后 Token 字符串会打印到 stdout。

同样，也可以用私钥签发：

$ bin/pulsar tokens create --private-key file:///path/to/my-private.key \ --subject test-user

还可以为 Token 预定义 TTL（存活时间）。超过该时间后，Token 会被自动作废：

$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --subject test-user \ --expiry-time 1y

结合 TokensCliUtils 中的CommandCreateToken（第 109~172 行），create子命令的完整行为如下：

过期时间通过RelativeTimeUtil.parseRelativeTimeInSeconds解析为相对秒数，再加到当前时间上作为 JWT 的expclaim；签名与组装则由 AuthTokenUtils 的createToken()完成（设置 subject，可选设置 expiration，最后compact()输出紧凑格式）。

密钥路径的灵活格式：--secret-key/--private-key/--public-key的值由AuthTokenUtils.readKeyFromUrl()（第 102~126 行）解析，按以下优先级尝试：data:或file:URL → 本地存在的文件路径 → 直接的 base64 字符串。因此除文档中的file:///path/...写法外，也可以直接内联 base64 内容。

4. 授权（Authorization）：给 Token 授予权限

Token 本身不携带任何权限。权限由授权引擎（authorization engine）决定。Token 创建之后，可以为其关联的角色授予特定操作的权限，例如：

$ bin/pulsar-admin namespaces grant-permission my-tenant/my-namespace \ --role test-user \ --actions produce,consume

也就是说：tokens create解决"你是谁"（认证），pulsar-admin namespaces grant-permission解决"你能做什么"（授权），两者缺一不可。

如果集群中部署了 Proxy，还需注意一点：Proxy 与 Broker 通信时会使用自己的角色（通常是一个专用角色），该角色需要加入 Broker 侧配置的proxyRoles中。ServiceConfiguration 中proxyRoles的定义（第 1395 行附近）也说明了其语义：来自proxyRoles中角色的请求，会被要求出示"原始客户端"的认证数据，从而保证 Proxy 不能伪造任意角色。授权细节可参考文档体系中的 "Authorization" 主题（security-authorization）。

5. 在 Broker 上启用 Token 认证

在broker.conf（仓库中的默认模板见 conf/broker.conf）中配置以下内容：

# Configuration to enable authentication and authorization authenticationEnabled=true authorizationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken # If using secret key (Note: key files must be DER-encoded) tokenSecretKey=file:///path/to/secret.key # The key can also be passed inline: # tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU= # If using public/private (Note: key files must be DER-encoded) # tokenPublicKey=file:///path/to/public.key

5.1 Broker 侧校验逻辑（源码解读）

配置项authenticationProviders指向的org.apache.pulsar.broker.authentication.AuthenticationProviderToken，其实现位于 AuthenticationProviderToken。关键行为均可在源码中印证：

1. 启动时加载校验密钥：initialize()（第 120~145 行）从配置读取tokenSecretKey/tokenPublicKey（二者至少配置其一，否则抛出 "No secret key was provided for token authentication"），并提前构建好JwtParser。密钥读取同样复用AuthTokenUtils.readKeyFromUrl()，所以file://路径与data:;base64,...内联两种方式都被支持——这正是broker.conf示例中两种写法能共存的底层原因。
2. 角色 claim 默认是sub：getTokenRoleClaim()（第 277~284 行）显示，若未配置tokenAuthClaim，则取 JWT 的sub（subject）字段作为角色名。这就是"生成 Token 时必须设置 subject"的必然性。
3. 公钥算法默认 RS256：getPublicKeyAlgType()（第 286~297 行）在未配置tokenPublicAlg时默认使用SignatureAlgorithm.RS256，与create-key-pair命令的默认算法保持一致。
4. HTTP 请求走 Bearer 头：getToken()（第 174~192 行）区分两种通道——Pulsar 二进制协议的CommandAuth数据，以及 HTTP 请求头Authorization: Bearer <token>（符合 RFC-6750）。
5. 过期时间持续受检：TokenAuthenticationState（第 319~375 行）在构造时记录 JWT 的 expiration，isExpired()会持续与当前时间比较；同时 Provider 注册了两个 Prometheus 指标pulsar_expired_token_count与pulsar_expiring_token_minutes（第 76~85 行），可在监控中观察 Token 过期情况。
6. 可选的 audience 校验：若配置了tokenAudienceClaim，则必须同时配置tokenAudience，authenticateToken()（第 207~232 行）会校验 Token 中该 claim 是否包含本 Broker 的 audience 值，用于在共享密钥的多服务集群间隔离 Token 的适用范围。

相关行为另有单元测试 AuthenticationProviderTokenTest 与端到端集成测试 TokenAuthWithSymmetricKeys 覆盖。

6. 在 Proxy 上启用 Token 认证

在proxy.conf（模板见 conf/proxy.conf）中配置如下：

# For clients connecting to the proxy authenticationEnabled=true authorizationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken tokenSecretKey=file:///path/to/secret.key # For the proxy to connect to brokers brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"} # Or, alternatively, read token from file # brokerClientAuthenticationParameters=file:///path/to/proxy-token.txt

注意 Proxy 处于"双重身份"：

• 对客户端：Proxy 用authenticationProviders中的 Token Provider 校验连接它的客户端；
• 对 Broker：Proxy 本身也是一个 Pulsar 客户端，需要携带自己的 Token 与 Broker 通信，通过brokerClientAuthenticationPlugin+brokerClientAuthenticationParameters配置。该角色应加入 Broker 的proxyRoles（见第 4 节）。

brokerClientAuthenticationParameters的解析逻辑在 AuthenticationToken 的configure()（第 73~91 行）中，支持四种写法：

1. {"token":"..."}形式的 JSON 字符串（上例）；
2. file:///path/to/token.txt—— 从文件读取 Token；
3. token:xxxx前缀形式；
4. 裸 Token 字符串（既不是 JSON 也不是 file: URL 时按此处理）。

7. 补充：Token 查看与校验命令

除文档重点介绍的create-secret-key、create-key-pair、create之外，pulsar tokens命令组（入口即 TokensCliUtils 的main，第 329~349 行按子命令分派）还提供两个日常运维常用的子命令：

• bin/pulsar tokens show：打印 Token 的 header 与 payload（Base64URL 解码后的 JSON），Token 可通过位置参数、--stdin、--token-file或环境变量TOKEN传入；
• bin/pulsar tokens validate：用--secret-key或--public-key校验一个 Token 的签名与有效期，成功后打印 claims 内容。

这两个命令适合在排查"客户端拿到的 Token 到底是谁签发的、何时过期"时快速定位问题。

小结

本文沿着官方文档《Token authentication admin》的完整脉络，覆盖了：对称/非对称两种密钥体系的创建（注意 DER 编码约束与默认算法 HS256/RS256）、带 subject 与相对过期时间的 Token 签发、通过grant-permission的授权衔接，以及 Broker 与 Proxy 两侧的配置。源码证据（TokensCliUtils、AuthTokenUtils、AuthenticationProviderToken、AuthenticationToken）进一步印证了每个配置项的实际生效路径，读者可按此在当前仓库中继续深入，例如查看 AuthenticationProviderTokenTest 中各类异常场景（无效签名、过期、错误 audience）的校验行为。

• 消息队列
• 后端
• 流处理