Client authentication using tokens based on JSON Web Tokens

You can use tokens to identify a Pulsar client and associate with some “principal” (or “role”) that is permitted to do some actions (eg: publish to a topic or consume from a topic).

A user typically gets a token string from the administrator (or some automated service).

The compact representation of a signed JWT is a string that looks like as the following:

Application specifies the token when you create the client instance. An alternative is to pass a “token supplier” (a function that returns the token when the client library needs one).

like pulsar-admin, , and pulsar-client use the config file in a Pulsar installation.

You need to add the following parameters to that file to use the token authentication with CLI tools of Pulsar:

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

The token string can also be read from a file, for example:

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

Pulsar client

  • Java
  • Python
  • Go
  • C++
  • C#
  2. PulsarClient client = PulsarClient.builder()
  3.     .serviceUrl("pulsar://broker.example.com:6650/")
  4.     .authentication(
  5.         AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")）
  6.     .build();

Similarly, you can also pass a Supplier:

  2. PulsarClient client = PulsarClient.builder()
  3.     .serviceUrl("pulsar://broker.example.com:6650/")
  4.     .authentication(
  5.         AuthenticationFactory.token(() -> {
  6.             // Read token from custom source
  7.         }))
  8.     .build();
  2. from pulsar import Client, AuthenticationToken
  4. client = Client('pulsar://broker.example.com:6650/'
  5.                 authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))

Alternatively, you can also pass a Supplier:

  3.     URL:            "pulsar://localhost:6650",
  4.     Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
  5. })

Similarly, you can also pass a Supplier:

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

Enable token authentication

On how to enable token authentication on a Pulsar cluster, you can refer to the guide below.

JWT supports two different kinds of keys in order to generate and validate the tokens:

  • Symmetric :
    • You can use a single Secret key to generate and validate tokens.
  • Asymmetric: A pair of keys consists of the Private key and the Public key.
    • You can use Private key to generate tokens.

When you use a secret key, the administrator creates the key and uses the key to generate the client tokens. You can also configure this key to brokers in order to validate the clients.

Output file is generated in the root of your Pulsar installation directory. You can also provide absolute path for the output file using the command below.

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

Enter this command to generate base64 encoded private key.

Create a key pair

Output file is generated in the root of your Pulsar installation directory. You can also provide absolute path for the output file using the command below.

  2. $ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
  • Store my-private.key in a safe location and only administrator can use my-private.key to generate new tokens.
  • my-public.key is distributed to all Pulsar brokers. You can publicly share this file without any security concern.

A token is the credential associated with a user. The association is done through the “principal” or “role”. In the case of JWT tokens, this field is typically referred as subject, though they are exactly the same concept.

Then, you need to use this command to require the generated token to have a subject field set.

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

This command prints the token string on stdout.

Similarly, you can create a token by passing the “private” key using the command below:

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

Finally, you can enter the following command to create a token with a pre-defined TTL. And then the token is automatically invalidated.

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

Authorization

The token itself does not have any permission associated. The authorization engine determines whether the token should have permissions or not. Once you have created the token, you can grant permission for this token to do certain actions. The following is an example.

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

To configure brokers to authenticate clients, add the following parameters to broker.conf:

Enable token authentication on Proxies

The proxy uses its own token when connecting to brokers. You need to configure the role token for this key pair in the proxyRoles of the brokers. For more details, see the authorization guide.

  2. # For clients connecting to the proxy
  3. authenticationEnabled=true
  4. authorizationEnabled=true
  5. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
  6. tokenSecretKey=file:///path/to/secret.key
  8. # For the proxy to connect to brokers
  9. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
  10. brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"}
  11. # Or, alternatively, read token from file
  12. # brokerClientAuthenticationParameters={"file":"///path/to/proxy-token.txt"}
  14. # Whether client authorization credentials are forwarded to the broker for re-authorization.