Athenz is a role-based authentication/authorization system. In Pulsar, Athenz role tokens (aka z-tokens) can be used to establish the identify of the client.
In a decentralized Athenz system there is both an authoriZation Management System (ZMS) server and an authoriZation Token System (ZTS) server.
To begin, you need to set up Athenz service access control. You should create domains for the provider (which provides some resources to other services with some authentication/authorization policies) and the tenant (which is provisioned to access some resources in a provider). In this case, the provider corresponds to the Pulsar service itself and the tenant corresponds to each application using Pulsar (typically, a tenant in Pulsar).
On the tenant side, you need to:
shopping
some_app
, on the domain with the public keyNote that the private key generated in step 2 needs to be specified when the Pulsar client connects to the broker (see client configuration examples for Java and C++).
For more specific steps involving the Athenz UI, please refer to this doc.
On the provider side, you need to:
pulsar
Note that in step 2 any action and resource can be specified since they are not used on Pulsar. In other words, Pulsar uses the Athenz role token only for authentication, not for authorization.
For more specific steps involving UI, please refer to this doc.
TLS encryption strongly recommended
Please note that using TLS encryption is strongly recommended when using Athenz as an authentication provider, as it can protect role tokens from being intercepted and reused (see also this doc).
In the conf/broker.conf
configuration file in your Pulsar installation, you need to provide the class name of the Athenz authentication provider as well as a comma-separated list of provider domain names.
# Add the Athenz auth provider authenticationEnabled=true authorizationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz athenzDomainNames=pulsar # Enable TLS tlsEnabled=true tlsCertificateFilePath=/path/to/broker-cert.pem tlsKeyFilePath=/path/to/broker-key.pem # 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.AuthenticationAthenz brokerClientAuthenticationParameters={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
A full listing of parameters available in the
conf/broker.conf
file, as well as the default values for those parameters, can be found in Broker Configuration.
For more information on Pulsar client authentication using Athenz, see the following language-specific docs:
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 authentication parameters to that file to use Athenz with Pulsar’s CLI tools:
# URL for the broker serviceUrl=https://broker.example.com:8443/ # Set Athenz auth plugin and its parameters authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"} # Enable TLS useTls=true tlsAllowInsecureConnection=false tlsTrustCertsFilePath=/path/to/cacert.pem