Client authentication using tokens based on JSON Web Tokens

Token 认证概述

Pulsar 支持通过加密 Token 的方式认证客户端，它是基于JSON Web Tokens（RFC-7519）来实现的。

你可以根据 Token 来识别 Pulsar 客户端。通过给 Token 关联一些 “principal” 或 “role”，可以用来授权客户端允许执行某些操作 (例如：发布消息主题或从主题消费消息) 。

用户通常需要从管理员（或某些自动化服务）获得 Token 字符串。

如下是一个简短的 JWT 签名字符串：

  1. eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY

应用程序需要在创建客户端实例时，指定所使用的 Token。 一个替代方法是通过“令牌供应商”(即通过一个函数返回所需要的Token)。

始终使用 TLS 传输加密

发送 Token 等同于在网络上发送密码。 在连接 Pulsar 服务的整个过程中，最好始终使用 TLS 加密。 有关详细信息，请参阅 使用 TLS 传输加密 。

命令行工具

命令行工具 pulsar-admin, pulsar-perf pulsar-client 使用 conf/client. onf 配置文件在 Pulsar 安装中。

你需要添加以下参数到该文件以使用 Pulsar 的 CLI 工具使用 Token 身份验证：

  1. webServiceUrl=http://broker.example.com:8080/
  2. brokerServiceUrl=pulsar://broker.example.com:6650/
  3. authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
  4. authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY

Token 字符串也可以从文件中读取，例如：

  1. authParams=file:///path/to/token/file

Pulsar 客户端

你可以使用 Token 对如下 Pulsar 客户端进行身份认证。

Java

Python

Go

C++

C#

  1. PulsarClient client = PulsarClient.builder()    .serviceUrl("pulsar://broker.example.com:6650/")    .authentication(        AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")）    .build();

同样，你也可以传入一个 Supplier：

  1. PulsarClient client = PulsarClient.builder()    .serviceUrl("pulsar://broker.example.com:6650/")    .authentication(        AuthenticationFactory.token(() -> {            // 从通用的数据源读取 Token            return readToken();        }))    .build();
  1. from pulsar import Client, AuthenticationTokenclient = Client('pulsar://broker.example.com:6650/'                authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))

或者，您也可以通过 Supplier：

  1. def read_token():    with open('/path/to/token.txt') as tf:        return tf.read().strip()client = Client('pulsar://broker.example.com:6650/'                authentication=AuthenticationToken(read_token))
  1. client, err := NewClient(ClientOptions{    URL:            "pulsar://localhost:6650",    Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),})

同样，你也可以传入一个 Supplier：

  1. client, err := NewClient(ClientOptions{    URL:            "pulsar://localhost:6650",    Authentication: NewAuthenticationTokenSupplier(func () string {        // Read token from custom source        return readToken()    }),})
  1. #include <pulsar/Client.h>pulsar::ClientConfiguration config;config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));pulsar::Client client("pulsar://broker.example.com:6650/", config);
  1. var client = PulsarClient.Builder()                         .AuthenticateUsingToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")                         .Build();

启用 Token 认证

根据如下指南，可以在 Pulsar 集群中启用 Token 认证。

JWT 支持通过两种不同的秘钥，来生成和验证 Token：

  • 对称秘钥：
    • 使用单个 Secret key 来生成和验证 tokens。
  • 非对称秘钥：包含由私钥和公钥组成的一对密钥。
    • 使用 Private key 生成 Token。
    • 使用 Public key 验证 Token。

创建 Secret key

使用 Secret key 时，由管理员创建这个 Secret key， 并使用该密钥生成客户端 Token。 为了能够验证客户端，还需要在 Broker 上配置这个 Key。

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

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

输入下面的命令可以生成 base64 编码的密钥。

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

创建秘钥对

若需要使用公钥和私钥方式，需要先创建一对秘钥。 Pulsar 支持 Java JWT 库（ 这里）支持的所有算法。

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

  1. $ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
  • 保存 my-private.key 到一个安全的位置，只有管理员能使用 my-private.key 来生成新的 tokens。
  • my-public.key 需要分发给所有 Pulsar brokers。 您可以公开共享此文件，不用担心安全问题。

生成 Token

A token is the credential associated with a user. 连接是通过 “principal” 或 “role” 完成的。 对于 JWT tokens，这个字段通常被称为 subject，尽管它们是完全相同的概念。

接下来，您需要使用这个命令来要求生成的具有一个 subject 字段的 token。

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

命令将在 stdout 上打印出 token 字符串。

类似地，您可以通过下面的命令使用 “private” key 来创建一个 token。

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

最后，你可以通过以下命令来创建一个带有过期时间的 Token。 Token 到期后会自动失效。

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

授权

Token 本身没有关联任何权限。 授权引擎确定 token 是否有权限。 一旦创建 token，就可以授予该 Token 执行某些操作的权限。 The following is an example.

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

在 Brokers 上启用 token 认证

要让 brokers 能对客户端进行身份认证，请在 broker.conf 中添加以下参数：

  1. # 启用认证和鉴权
  2. authenticationEnabled=true
  3. authorizationEnabled=true
  4. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
  6. # 设置 broker 自身的认证。 当 broker 连接到其他的 broker 时使用。可以是本集群的 broker 也可以是其他集群的 broker。
  7. brokerClientTlsEnabled=true
  8. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
  9. brokerClientAuthenticationParameters=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw
  11. # 或者从文件里面读取 token
  12. # brokerClientAuthenticationParameters=file:///path/to/proxy-token.txt
  13. brokerClientTrustCertsFilePath=/path/my-ca/certs/ca.cert.pem
  15. # 如果设置此项，broker 将对原始的认证信息进行认证，
  16. # 否则只接受原始规则，并对其进行认证(如果需要的话)。
  17. authenticateOriginalAuthData=true
  19. # 如果使用的是 secret key (注意: 秘钥文件必须是 DER-encoded 编码)
  20. tokenSecretKey=file:///path/to/secret.key
  21. # The key can also be passed inline:
  22. # tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
  24. # 如果使用的是 public/private (注意: 秘钥文件必须是 DER-encoded 编码)
  25. # tokenPublicKey=file:///path/to/public.key

Proxy 启用 Token 认证

要让 Proxy 能对客户端进行身份认证，请在 proxy.conf 中添加以下参数：

Proxy 连接 brokers 使用的是自己的 token。 你需要在 broker 的 代理角色 中配置此密钥对的角色标记。 有关详细信息，请参阅 授权指南。

  1. # 对于连接到代理的客户端
  2. authenticationEnabled=true
  3. authorizationEnabled=true
  4. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
  5. tokenSecretKey=file:///path/to/secret.key
  7. # 对于连接到 broker 的代理
  8. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
  9. brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"}
  10. # 或者从文件里面读取 Token
  11. # brokerClientAuthenticationParameters={"file":"///path/to/proxy-token.txt"}
  13. # 是否将客户端授权凭据转发给 broker 进行重新授权。
  14. # Authentication must be enabled via authenticationEnabled=true for this to take effect.
  15. forwardAuthorizationCredentials=true