Athenz is a role-based authentication/authorization system. In Pulsar, you can use Athenz role tokens (also known as z-tokens) to establish the identify of the client.
A decentralized Athenz system contains 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 need to 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 do the following things:
shopping
some_app
, on the domain with the public keyNote that you need to specify the private key generated in step 2 when the Pulsar client connects to the broker (see client configuration examples for Java and C++).
For more specific steps involving the Athenz UI, refer to Example Service Access Control Setup.
On the provider side, you need to do the following things:
pulsar
Note that you can specify any action and resource in step 2 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, refer to Example Service Access Control Setup.
TLS encryption
Note that when you are using Athenz as an authentication provider, you had better use TLS encryption as it can protect role tokens from being intercepted and reused. (for more details involving TLS encrption see Architecture - Data Model).
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 is available in the
conf/broker.conf
file, you can also find the default values for those parameters 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 need to add the following authentication parameters to the conf/client.conf
config file to use Athenz with CLI tools of Pulsar:
# 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