Authentication using Athenz

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.

Athenz authentication settings

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

Create the tenant domain and service

On the tenant side, you need to do the following things:

  1. Create a domain, such as shopping
  2. Generate a private/public key pair
  3. Create a service, such as some_app, on the domain with the public key

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

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

On the provider side, you need to do the following things:

  1. Create a domain, such as pulsar
  2. Create a role
  3. Add the tenant service to members of the role

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.

Configure the broker for Athenz

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

  2. # Add the Athenz auth provider
  3. authenticationEnabled=true
  4. authorizationEnabled=true
  5. authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderAthenz
  6. athenzDomainNames=pulsar
  8. # Enable TLS
  9. tlsEnabled=true
  10. tlsCertificateFilePath=/path/to/broker-cert.pem
  11. tlsKeyFilePath=/path/to/broker-key.pem
  13. # Authentication settings of the broker itself. Used when the broker connects to other brokers, either in same or other clusters
  14. brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationAthenz
  15. 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.

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 need to add the following authentication parameters to the conf/client.conf config file to use Athenz with CLI tools of Pulsar:

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