Token authentication admin

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.

Always use TLS transport encryption

Sending a token is equivalent to sending a password over the wire. It is strongly recommended toalways use TLS encryption when talking to the Pulsar service. SeeTransport Encryption using TLS

Secret vs Public/Private keys

JWT support two different kind of keys in order to generate and validate the tokens:

  • Symmetric :
    • there is a single Secret key that is used both to generate and validate
  • Asymmetric: there is a pair of keys.
    • Private key is used to generate tokens
    • Public key is used to validate tokens

Secret key

When using a secret key, the administrator will create the key and he willuse it to generate the client tokens. This key will be also configured tothe brokers to allow them to validate the clients.

Creating a secret key

Output file will be generated in the root of your pulsar installation directory. You can also provide absolute path for the output file.

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

To generate base64 encoded private key

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

Public/Private keys

With public/private, we need to create a pair of keys. Pulsar supports all algorithms supported by the Java JWT library shown here

Creating a key pair

Output file will be generated in the root of your pulsar installation directory. You can also provide absolute path for the output file.

  1. $ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
  • my-private.key will be stored in a safe location and only used by administrator to generatenew tokens.
  • my-public.key will be distributed to all Pulsar brokers. This file can be publicly shared withoutany security concern.

Generating tokens

A token is the credential associated with a user. The association is done through the "principal",or "role". In case of JWT tokens, this field it's typically referred to as subject, thoughit's exactly the same concept.

The generated token is then required to have a subject field set.

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

This will print the token string on stdout.

Similarly, one can create a token by passing the "private" key:

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

Finally, a token can also be created with a pre-defined TTL. After that time,the token will be automatically invalidated.

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

Authorization

The token itself doesn't have any permission associated. That will be determined by theauthorization engine. Once the token is created, one can grant permission for this token to do certainactions. Eg. :

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

Enabling Token Authentication …

… on Brokers

To configure brokers to authenticate clients, put the following in broker.conf:

  1. # Configuration to enable authentication and authorization
  2. authenticationEnabled=true
  3. authorizationEnabled=true
  4. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
  6. # If using secret key
  7. tokenSecretKey=file:///path/to/secret.key
  8. # The key can also be passed inline:
  9. # tokenSecretKey=data:base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU=
  11. # If using public/private
  12. # tokenPublicKey=file:///path/to/public.key

… on Proxies

To configure proxies to authenticate clients, put the following in proxy.conf:

The proxy will have its own token used when talking to brokers. The role token for thiskey pair should be configured in the proxyRoles of the brokers. See the authorization guide for more details.

  1. # For clients connecting to the proxy
  2. authenticationEnabled=true
  3. authorizationEnabled=true
  4. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
  5. tokenSecretKey=file:///path/to/secret.key
  7. # For the proxy to connect to brokers
  8. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken
  9. brokerClientAuthenticationParameters=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw
  10. # Or, alternatively, read token from file
  11. # brokerClientAuthenticationParameters=file:///path/to/proxy-token.txt