import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
Pulsar supports authenticating clients using security tokens that are based on JSON Web Tokens (RFC-7519).
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 the following:
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
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).
:::note
Always use TLS transport encryption when you connect to the Pulsar service, because sending a token is equivalent to sending a password over the wire. See Transport Encryption using TLS for more details.
:::
Command-line tools like pulsar-admin, pulsar-perf, and pulsar-client use the conf/client.conf 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:
webServiceUrl=http://broker.example.com:8080/ brokerServiceUrl=pulsar://broker.example.com:6650/ authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken authParams=token:eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY
The token string can also be read from a file, for example:
authParams=file:///path/to/token/file
You can use tokens to authenticate the following Pulsar clients.
<Tabs groupId="lang-choice" defaultValue="Java" values={[{"label":"Java","value":"Java"},{"label":"Python","value":"Python"},{"label":"Go","value":"Go"},{"label":"C++","value":"C++"},{"label":"C#","value":"C#"}]}> <TabItem value="Java"> ```java PulsarClient client = PulsarClient.builder() .serviceUrl("pulsar://broker.example.com:6650/") .authentication( AuthenticationFactory.token("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")） .build(); ``` Similarly, you can also pass a `Supplier`: ```java PulsarClient client = PulsarClient.builder() .serviceUrl("pulsar://broker.example.com:6650/") .authentication( AuthenticationFactory.token(() -> { // Read token from custom source return readToken(); })) .build(); ``` </TabItem> <TabItem value="Python"> ```python from pulsar import Client, AuthenticationToken client = Client('pulsar://broker.example.com:6650/' authentication=AuthenticationToken('eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY')) ``` Alternatively, you can also pass a `Supplier`: ```python 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)) ``` </TabItem> <TabItem value="Go"> ```go client, err := NewClient(ClientOptions{ URL: "pulsar://localhost:6650", Authentication: NewAuthenticationToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY"), }) ``` Similarly, you can also pass a `Supplier`: ```go client, err := NewClient(ClientOptions{ URL: "pulsar://localhost:6650", Authentication: NewAuthenticationTokenSupplier(func () string { // Read token from custom source return readToken() }), }) ``` </TabItem> <TabItem value="C++"> ```c++ #include <pulsar/Client.h> pulsar::ClientConfiguration config; config.setAuth(pulsar::AuthToken::createWithToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY")); pulsar::Client client("pulsar://broker.example.com:6650/", config); ``` </TabItem> <TabItem value="C#"> ```c# var client = PulsarClient.Builder() .AuthenticateUsingToken("eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.ipevRNuRP6HflG8cFKnmUPtypruRC4fb1DWtoLL62SY") .Build(); ``` </TabItem> </Tabs>
JWT supports two different kinds of keys in order to generate and validate the 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.
The output file is generated in the root of your Pulsar installation directory. You can also provide an absolute path for the output file using the command below.
$ bin/pulsar tokens create-secret-key --output my-secret.key
Enter this command to generate a base64 encoded private key.
$ bin/pulsar tokens create-secret-key --output /opt/my-secret.key --base64
With Public and Private keys, you need to create a pair of keys. Pulsar supports all algorithms that the Java JWT library (shown here) supports.
The output file is generated in the root of your Pulsar installation directory. You can also provide an absolute path for the output file using the command below.
$ bin/pulsar tokens create-key-pair --output-private-key my-private.key --output-public-key my-public.key
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 a 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.
$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --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:
$ bin/pulsar tokens create --private-key file:///path/to/my-private.key \ --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.
$ bin/pulsar tokens create --secret-key file:///path/to/my-secret.key \ --subject test-user \ --expiry-time 1y
:::tip
The token itself does not have any permission associated. The authorization engine determines whether the token can have permissions or not. You need to enable authorization and assign superusers, and then use the bin/pulsar-admin namespaces grant-permission command to grant permissions for tokens.
:::
To configure brokers to authenticate clients, add the following parameters to the conf/broker.conf or conf/standalone.conf file.
# Configuration to enable authentication authenticationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken # Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters brokerClientTlsEnabled=true brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationToken brokerClientAuthenticationParameters={"token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0LXVzZXIifQ.9OHgE9ZUDeBTZs7nSMEFIuGNEX18FLR3qvy8mqxSxXw"} # Either configure the token string or specify to read it from a file. The following three available formats are all valid: # brokerClientAuthenticationParameters={"token":"your-token-string"} # brokerClientAuthenticationParameters=token:your-token-string # brokerClientAuthenticationParameters=file:///path/to/token brokerClientTrustCertsFilePath=/path/my-ca/certs/ca.cert.pem # If this flag is set then the broker authenticates the original Auth data # else it just accepts the originalPrincipal and authorizes it (if required). authenticateOriginalAuthData=true # If using secret key (Note: key files must be DER-encoded) tokenSecretKey=file:///path/to/secret.key # The key can also be passed inline: # tokenSecretKey=data:;base64,FLFyW0oLJ2Fi22KKCm21J18mbAdztfSHN/lAT5ucEKU= # If using public/private (Note: key files must be DER-encoded) # tokenPublicKey=file:///path/to/public.key
:::note
Equivalent to brokerClientAuthenticationParameters, you need to configure authParams in the conf/client.conf file.
:::
To configure proxies to authenticate clients, add the following parameters to the conf/proxy.conf file.
# For clients connecting to the proxy authenticationEnabled=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"} # Either configure the token string or specify to read it from a file. The following three available formats are all valid: # brokerClientAuthenticationParameters={"token":"your-token-string"} # brokerClientAuthenticationParameters=token:your-token-string # brokerClientAuthenticationParameters=file:///path/to/token
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 authorization.