Authentication using Athenz

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.

Athenz authentication settings

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).

Create the tenant domain and service

On the tenant side, you need to:

  • Create a domain, such as shopping
  • Generate a private/public key pair
  • Create a service, such as 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.

Create the provider domain and add the tenant service to some role members

On the provider side, you need to:

  • Create a domain, such as pulsar
  • Create a role
  • Add the tenant service to members of the roleNote 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.

Configure the broker for Athenz

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.

  1. # Add the Athenz auth provider
  2. authenticationEnabled=true
  3. authorizationEnabled=true
  4. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
  5. athenzDomainNames=pulsar
  7. # Enable TLS
  8. tlsEnabled=true
  9. tlsCertificateFilePath=/path/to/broker-cert.pem
  10. tlsKeyFilePath=/path/to/broker-key.pem

A full listing of parameters available in the conf/broker.conf file, as well as the defaultvalues for those parameters, can be found in Broker Configuration.

Configure clients for Athenz

For more information on Pulsar client authentication using Athenz, see the following language-specific docs:

Configure CLI tools for Athenz

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:

  1. # URL for the broker
  2. serviceUrl=https://broker.example.com:8443/
  4. # Set Athenz auth plugin and its parameters
  5. authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
  6. authParams={"tenantDomain":"shopping","tenantService":"some_app","providerDomain":"pulsar","privateKey":"file:///path/to/private.pem","keyId":"v1"}
  8. # Enable TLS
  9. useTls=true
  10. tlsAllowInsecureConnection=false
  11. tlsTrustCertsFilePath=/path/to/cacert.pem