Token Authentication Overview
Tokens are used to identify a Pulsar client and associate with some "principal" (or "role") which will 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:
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY ``` Application will specify the token when creating the client instance. An alternative is to pass a "token supplier", that is to say a function that returns the token when the client library will need one. > #### Always use TLS transport encryption > Sending a token is equivalent to sending a password over the wire. It is strongly recommended to > always use TLS encryption when talking to the Pulsar service. See > [Transport Encryption using TLS](security-tls-transport.md) ## 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 will use it to generate the client tokens. This key will be also configured to the 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. ```shell $ bin/pulsar tokens create-secret-key --output my-secret.key
To generate base64 encoded private key
bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64
With public/private, we need to create a pair of keys.
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.
bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
my-private.keywill be stored in a safe location and only used by administrator to generate new tokens.
my-public.keywill be distributed to all Pulsar brokers. This file can be publicly shared without any security concern.
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, though it's exactly the same concept.
The generated token is then required to have a subject field set.
bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --subject test-user
This will print the token string on stdout.
Similarly, one can create a token by passing the "private" key:
bin/pulsar tokens create --private-key file:///path/to/my-private.key \ --subject test-user
Finally, a token can also be created with a pre-defined TTL. After that time, the token will be automatically invalidated.
bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --subject test-user \ --expiry-time 1y
The token itself doesn't have any permission associated. That will be determined by the authorization engine. Once the token is created, one can grant permission for this token to do certain actions. Eg. :
bin/pulsar-admin namespaces grant-permission my-tenant/my-namespace \ --role test-user \ --actions produce,consume
Enabling Token Authentication ...
... on Brokers
To configure brokers to authenticate clients, put the following in
# Configuration to enable authentication and authorization authenticationEnabled=true authorizationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken # If using secret key tokenSecretKey=file:///path/to/secret.key # The key can also be passed inline: # tokenSecretKey=data:base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU= # If using public/private # tokenPublicKey=file:///path/to/public.key # operations and publish/consume from all topics superUserRoles=admin # Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken brokerClientAuthenticationParameters=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw # Or, alternatively, read token from file # brokerClientAuthenticationParameters=file:///path/to/admin-token.txt
... on Proxies
To configure proxies to authenticate clients, put the following in
The proxy will have its own token used when talking to brokers. The role token for this key pair should be configured in the
proxyRoles of the brokers. See the authorization guide for more details.
# 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