Setup ZTS (authoriZation Token System) for Production¶
- Getting Software
- Start/Stop ZTS Server
The following tools are required to be installed on hosts configured to run ZTS server.
ZTS Server is written in Java and using embedded Jetty.
While ZTS has been developed and tested with Oracle Java Platform JDK 8 it should run successfully with OpenJDK 8 as well.
Build the latest ZTS binary release by following the
development instructions. The binary release
packages will be created automatically in the
athenz-zts-X.Y-bin.tar.gz to your desired setup directory.
$ tar xvfz athenz-zts-X.Y-bin.tar.gz $ cd athenz-zts-X.Y
To run ZTS Server, the system administrator must generate the keys and make necessary changes to the configuration settings.
Private/Public Key Pair¶
Generate a unique private/public key pair that ZTS Server will use
to sign any ZTokens it issues. From the
execute the following commands:
$ cd var/zts_server/keys $ openssl genrsa -out zts_private.pem 2048 $ openssl rsa -in zts_private.pem -pubout > zts_public.pem
Server X509 Certificate¶
While it is still possible to generate and use a self-signed X509 certificate for ZTS Servers, it is recommended to purchase one for your production server from a well known certificate authority. Having such a certificate installed on your ZTS Servers will no longer require to distribute the server's public certificate to other hosts (e.g. Hosts running ZPU).
Follow the instructions provided by the Certificate Authority to
generate your private key and then the Certificate Request (CSR).
Once you have received your X509 certificate, we just need to add
that certificate along with its private key to a keystore for Jetty
use. From the
athenz-zts-X.Y directory execute the following
$ openssl pkcs12 -export -out zts_keystore.pkcs12 -in zts_cert.pem -inkey zts_key.pem
Register ZTS Service¶
In order for ZTS to access ZMS domain data, it must identify itself
as a registered service in ZMS. Using the
zms-cli utility, we will
register a new service in
sys.auth domain. Since ZMS Servers should
be running with a X509 certificate from a well know certificate
authority (not a self-signed one) we don't need to reference the CA
cert like we did for the local/development environment setup.
$ cd athenz-zts-X.Y $ bin/<platform>/zms-cli -z https://<zms-server>:4443/zms/v1 -d sys.auth add-service zts 0 var/zts_server/keys zts_public.pem
Athenz CA X.509 Certificate Issuing¶
For authenticating services using X509 certificates, ZTS Servers expect
the configured cert signer factory class names in its
athenz.zts.cert_signer_factory_class system property.
We already have below implementation of cert Signer:
- Self Cert Signer com.yahoo.athenz.zts.cert.impl.SelfCertSignerFactory for the dev environment.
- Http Cert Signer com.yahoo.athenz.zts.cert.impl.HttpCertSignerFactory for the production environment.
You can use HttpCert Signer or have your implementation of Cert Signer.
Refer Certificate Signer for full details how to implement your own certificate signer.
Generate Athenz Configuration File¶
Generate an Athenz configuration file
directory to include the ZMS 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 Server:
$ cd athenz-zts-X.Y $ bin/<platform>/athenz-conf -o conf/zts_server/athenz.conf -z https://<zms-server>:4443/ -t https://<zts-server>:8443/
Start/Stop ZTS Server¶
Start the ZTS Server by executing:
$ cd athenz-zts-X.Y $ bin/zts start
Based on the sample configuration file provided, ZTS Server will be listening on port 8443.
Stop the ZTS Server by executing:
$ cd athenz-zts-X.Y $ bin/zts stop