Add Athenz documentation (apache#301)

yciabaud · Mar 23, 2017 · b7bc381 · b7bc381
1 parent a86b6df
commit b7bc381
Showing 1 changed file with 101 additions and 0 deletions.
diff --git a/docs/Authentication.md b/docs/Authentication.md
@@ -12,6 +12,11 @@
 		- [Configure Java client](#configure-java-client)
 		- [Configure C++ client](#configure-c-client)
 		- [Configure CLI tools](#configure-cli-tools)
+	- [Athenz](#athenz)
+		- [Athenz authentication settings](#athenz-authentication-settings)
+		- [Configure broker](#configure-broker-1)
+		- [Configure Java client](#configure-java-client-1)
+		- [Configure CLI tools](#configure-cli-tools-1)
 
 <!-- /TOC -->
 
@@ -172,3 +177,99 @@ useTls=true
 tlsAllowInsecureConnection=false
 tlsTrustCertsFilePath=/path/to/cacert.pem
 ```
+
+### Athenz
+
+[Athenz](https://github.com/yahoo/athenz) is one of the role-based authentication/authorization systems.
+In Pulsar, Athenz ***RoleToken*** (also called ***Z-Token***) can be used as the identity of the client.
+
+#### Athenz authentication settings
+
+Assume that we have the [***decentralized*** Athenz system](https://github.com/yahoo/athenz/blob/master/docs/dev_decentralized_access.md), i.e., there is not only the ***ZMS*** server but also the ***ZTS*** server.
+
+At first we set up the service access control in Athenz.
+We 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, provider corresponds to the Pulsar service itself and tenant corrensponds to each application using Pulsar (typically, Property on Pulsar).
+
+##### Create the tenant domain and service
+
+For the tenant side, we should
+
+1. Create a domain (e.g. *shopping*)
+2. Generate a private/public key pair
+3. Create a service (e.g. *some_app*) on the domain with the public key
+
+Note that the private key generated in the step 2 needs to be specified when the pulsar client connects to the Broker (see the latter client configuration examples).
+
+For more specific steps using UI, please refer [example_service_athenz_setup.md#client-tenant-domain](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#client-tenant-domain).
+
+##### Create the provider domain and add the tenant service to some role members
+
+For the provider side, we should
+
+1. Create a domain (e.g. *pulsar*)
+2. Create a role
+3. Add the tenant service to members of the role
+
+Note that in step 2, any action and resource can be specified since they are not used on Pulsar. (In other words, Pulsar uses Athenz RoleToken for only authentication, not authorization).
+
+For more specific steps using UI, please refer [example_service_athenz_setup.md#server-provider-domain](https://github.com/yahoo/athenz/blob/master/docs/example_service_athenz_setup.md#server-provider-domain).
+
+#### Configure broker
+
+The class name of the Athenz authentication provider and comma separated provider domain names need to be specified in `conf/broker.conf`. Note that using TLS encryption is strongly recommended to protect RoleTokens against intercepting and reusing (see also [data_model](https://github.com/yahoo/athenz/blob/master/docs/data_model.md)).
+
+```shell
+# Add Athenz auth provider
+authenticationEnabled=true
+authorizationEnabled=true
+authenticationProviders=com.yahoo.pulsar.broker.authentication.AuthenticationProviderAthenz
+athenzDomainNames=pulsar
+
+# Enable TLS
+tlsEnabled=true
+tlsCertificateFilePath=/path/to/broker-cert.pem
+tlsKeyFilePath=/path/to/broker-key.pem
+```
+
+#### Configure Java client
+
+4 parameters: `tenantDomain`, `tenantService`, `providerDomain`, `privateKeyPath` and an optional parameter `keyId` need to be configured. Note again that TLS is recommended.
+
+```java
+ClientConfiguration conf = new ClientConfiguration();
+
+// Enable TLS
+conf.setUseTls(true);
+conf.setTlsTrustCertsFilePath("/path/to/cacert.pem");
+
+// Set Athenz auth plugin and its parameters
+Map<String, String> authParams = new HashMap<>();
+authParams.put("tenantDomain", "shopping"); // Tenant domain name
+authParams.put("tenantService", "some_app"); // Tenant service name
+authParams.put("providerDomain", "pulsar"); // Provider domain name
+authParams.put("privateKeyPath", "/path/to/private.pem"); // Tenant private key path 
+authParams.put("keyId", "v1"); // Key id for the tenant private key (optional, default: "0")
+conf.setAuthentication(AuthenticationAthenz.class.getName(), authParams);
+
+PulsarClient client = PulsarClient.create(
+                        "pulsar+ssl://my-broker.com:6651", conf);
+```
+
+#### Configure CLI tools
+
+Command line tools like `pulsar-admin`, `pulsar-perf` and `pulsar-client` use the `conf/client.conf` config file and we can
+add there the authentication parameters:
+
+```shell
+serviceUrl=https://broker.example.com:8443/
+
+# Set Athenz auth plugin and its parameters
+authPlugin=com.yahoo.pulsar.client.impl.auth.AuthenticationAthenz
+authParams=tenantDomain:shopping,tenantService:some_app,providerDomain:pulsar,privateKeyPath:/path/to/private.pem,keyId:v1
+
+# Enable TLS
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/cacert.pem
+```