Client Authentication using tokens

Token Authentication Overview

Pulsar supports authenticating clients using security tokens that are based onJSON Web Tokens (RFC-7519).

Tokens are used to identify a Pulsar client and associate with some "principal" (or "role") whichwill be then granted permissions to do some actions (eg: publish or consume from a topic).

A user will typically be given a token string by an administrator (or some automated service).

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

  1.  eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY

Application will specify the token when creating the client instance. An alternative is to passa "token supplier", that is to say a function that returns the token when the client librarywill need one.

See Token authentication admin for a reference on how to enable tokenauthentication on a Pulsar cluster.

CLI tools

Command-line tools like pulsar-admin, pulsar-perf, and pulsar-client use the conf/client.conf config file in a Pulsar installation.

You'll need to add the following parameters to that file to use the token authentication withPulsar's CLI tools:

  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

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

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

Java client

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

Similarly, one can also pass a Supplier:

  1. PulsarClient client = PulsarClient.builder()
  2.     .serviceUrl("pulsar://broker.example.com:6650/")
  3.     .authentication(
  4.         AuthenticationFactory.token(() -> {
  5.             // Read token from custom source
  6.             return readToken();
  7.         })
  8.     .build();

Python client

  1. from pulsar import Client, AuthenticationToken
  3. client = Client('pulsar://broker.example.com:6650/'
  4.                 authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY'))

Alternatively, with a supplier:

  2. def read_token():
  3.     with open('/path/to/token.txt') as tf:
  4.         return tf.read().strip()
  6. client = Client('pulsar://broker.example.com:6650/'
  7.                 authentication=AuthenticationToken(read_token))

Go client

  1. client, err := NewClient(ClientOptions{
  2.     URL:            "pulsar://localhost:6650",
  3.     Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"),
  4. })

Alternatively, with a supplier:

  1. client, err := NewClient(ClientOptions{
  2.     URL:            "pulsar://localhost:6650",
  3.     Authentication: NewAuthenticationTokenSupplier(func () string {
  4.         // Read token from custom source
  5.         return readToken()
  6.     }),
  7. })

C++ client

  1. #include <pulsar/Client.h>
  3. pulsar::ClientConfiguration config;
  4. config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"));
  6. pulsar::Client client("pulsar://broker.example.com:6650/", config);