Project: Athenz (Provisioning / Key Management)
File: setup_zpu.md

-- ZPU is only needed to support decentralized authorization. The policy updater is the utility that retrieves from ZTS the policy files for provisioned domains on a host, which ZPE uses to evaluate access requests. * * * The following tools are required to be installed on hosts configured to run ZPE Policy Updater. Download latest ZPU binary release from from : click on the `Browse` button, choose the latest version directory and then download the `athenz-utils-<latest-version>-bin.tar.gz`. ```shell $ tar xvfz athenz-utils-X.Y-bin.tar.gz ``` To successfully run ZPU, the domain administrator must update a couple of settings files and generate a java truststore the utility. Before running ZPU utility, the system administrator must configure what domains are provisioned on the host so the utility can retrieve the policy files for those domains only. Create a configuration settings file with the following content: ```json { "domains": "<domain1>,<domain2>", "caCertFile": "<path to caCert file>" } ``` In the json file, edit the value for the "domains" field and specify a comma separated list of domain names. ZPU needs to access ZTS Server to download all domain policies in order to execute authorization checks. Since ZTS Server is running with a self-signed certificate, we need to generate a truststore for the java http client to use when communicating with the ZTS Server. From your ZTS Server installation, copy the `ztscert.pem` file from the `athenz-zts-X.Y/var/ztsserver/certs` directory to another directory that is configured as the value of the `caCertFile` setting in the zpu configuration file. -- Generate an Athenz configuration file `athenz.conf` in a directory to include the ZTS Server URL and the registered public keys that the athenz client libraries and utilities will use to establish connection and validate any data signed by the ZMS and ZTS Servers. To communicate with ZMS over SSL, the utility needs to have access to the ZMS Server's public certificate, so you need to copy the `zms_cert.pem` file from the `athenz-zms-X.Y/var/zms_server/certs` directory to a local directory and execute the following cmmmand: ```shell $ bin/<platform>/athenz-conf -o <path-to-athenz.conf> -c <path-to-zms_cert.pem> -z https://<zms-server>:4443/ -t https://<zts-server>:8443/ ``` By default ZPU will save any downloaded policy files in the `${ROOT}/var/zpe` directory. You need to make sure this is the directory where ZPE is configured to look for policy files. Set the required Athenz ROOT environment variable to the required directory and from there start the ZPU utility by executing: ```shell $ export ROOT=<full-path-to-required-root-directory> $ zpu -athenzConf <Athenz conf file> -zpuConf <zpu conf file> ``` The ZPU utility needs to run periodically so it can automatically download any modified policy files for the configured list of domains. The system administrator should setup this utility to be automatically executed by cron utility at least once every couple of hours. Checkout the for details how to manually validate the signatures in the policy file. This would be necessary if you'll be writing your own authorization policy engine library instead of using the Athenz provided one.