Setup ZMS (AuthoriZation Management System) For Production
The primary requirement for running ZMS in a Production environment is using JDBC (MySQL Server) to store the domain data as opposed to file based json documents.
- Getting Software
- Start/Stop ZMS Server
The following tools are required to be installed on hosts configured to run ZMS server.
ZMS Server is written in Java and using embedded Jetty.
While ZMS has been developed and tested with Oracle Java Platform JDK 8 it should run successfully with OpenJDK 8 as well.
On a separate host, download and install the latest version of MySQL Server
ZMS Server Schema Setup
zms_server.sql file from the Athenz Git repository (from the
servers/zms/schema directory) onto this host and create the database:
$ mysql -u root < zms_server.sql
MySQL User and Permissions
Follow MySQL documentation to create a user and grant this user full privileges over the zms_server database created. For example, let's assume our ZMS Server will be running on zms1.athenz.com host and we want to create a user called zms_admin with password "rdvXC7wgvm3g":
$ mysql -u root mysql> CREATE USER 'zms_admin'@'zms1.athenz.com' IDENTIFIED BY 'rdvXC7wgvm3g'; mysql> GRANT ALL PRIVILEGES ON zms_server.* TO 'zms_admin'@'zms1.athenz.com'; mysql> FLUSH PRIVILEGES;
We recommend to have a strong admin password for better security.
Download latest ZMS binary release from
$ tar xvfz athenz-zms-X.Y-bin.tar.gz $ cd athenz-zms-X.Y
To run ZMS Server, the system administrator must generate the keys and make necessary changes to the configuration settings.
In the "MySQL Server" section above we installed and configured the schema required for ZMS Server. We also created a zms admin user and granted full access over those tables. Now, we need to configure the ZMS with those access details:
$ cd conf/zms_server $ vi zms.properties
Make the following changes:
- Configure the ZMS Server to use JDBC object store implementation.
#athenz.zms.object_store_factory_class=line and set it to point to the JDBC Factory class name. It should be set to:
- Uncomment the
#athenz.zms.jdbcstore=line and set it to point to your MySQL Server instance. For example if your DB Server is running on a host called db1.athenz.com, then your line would be:
- Uncomment the
#athenz.zms.jdbc_user=line and set it to the user configured to have full access over zms server database:
- Uncomment the
#athenz.zms.jdbc_password=line and set it to the configured password the for the jdbc user with full access:
Storing the password in property file is not secure. The more robust approach
is to use a Key Management Store like HashiCorp Vault to store your passwords.
Athenz provides a PrivateKeyStoreFactory interface for accessing secrets from
your key management store. The recommended approach would to write your own
implementation of this interface and configure ZMS server to use that factory
to fetch the password for your database access. ZMS Server expect the private
key store factory implementation class name in its
athenz.zms.private_key_store_factory_class system property.
Refer to Private Key Store section for full details how to implement your private key store.
When storing the jdbc user password for your database access in your key management
store with a given keyname like
athenz.admin_db_password and using your own
implementation of the PrivateKeyStoreFactory, then the value of the
athenz.zms.jdbc_password property would be the key name. For example:
The password is retrieved using the
getApplicationSecret() of your private
key store class that takes keyName (
athenz.admin_db_password in this case)
as input and returns key value that is your configured password.
Generate a unique private key that ZMS Server will use
to sign any NTokens it issues. From the
execute the following commands:
$ cd var/zms_server/keys $ openssl genrsa -out zms_private.pem 2048
If you have multiple ZMS servers in your environment, your private key must be stored in your key management store and securely installed on all hosts where ZMS servers will be running in the specified directory.
Server X509 Certificate
While it is still possible to generate and use a self-signed X509 certificate for ZMS Servers, it is recommended to purchase one for your production server from a well known certificate authority. Having such a certificate installed on your ZMS Servers will no longer require to distribute the server's CA certificate to other hosts (e.g. ZTS Servers, Hosts running ZPU).
Follow the instructions provided by the Certificate Authority that
you're going to purchase your certificate from 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-zms-X.Y directory execute the following
$ openssl pkcs12 -export -out zms_keystore.pkcs12 -in zms_cert.pem -inkey zms_key.pem
For a user to authenticate himself/herself in ZMS, the server must have the appropriate authentication authority implementation configured. By default, ZMS enables the following two authorities:
- Unix User Authority - using pam login profile to authenticate users
- Principal Authority - validating Principal Tokens that are issued when users authenticate using their unix login password.
The server also provides other authorities - e.g. Kerberos, TLS Certificate that are not enabled by default. Since the default setup includes Unix Authority, the user that the ZMS process runs as must have read access to the /etc/shadow file. There are two options available:
- Create a special Unix group that has read access to the /etc/shadow file and set the user that the ZMS process will be running as a member of that group.
- Run the process as root using sudo. This is not recommended for a production installation.
To add your own authentication authority modify the
athenz.zms.authority_classes=com.yahoo.athenz.auth.impl.PrincipalAuthority,com.yahoo.athenz.auth.impl.UserAuthority line and include comma
separated list of authority implementation classes to support.
When running the server very first time, ZMS Server automatically creates the required domains and sets the running user as the system administrator. The system administrators are the only ones authorized to create top level domains in Athenz. Before running the server very first time, you can configure the set of system administrators by following these steps:
$ cd athenz-zms-X.Y $ vi conf/zms_server/zms.properties
athenz.zms.domain_admin=user.admin line and include comma
separated list of unix user ids that should be set as Athenz system
Start/Stop ZMS Server
Start the ZMS Server by executing:
$ cd athenz-zms-X.Y $ bin/zms start
If using the Unix Authority to authenticate users against their unix password,
make sure the user that the ZMS Server process is running as has read
access to the /etc/shadow file. For full details, please check out
User Authentication section above.
Based on the sample configuration file provided, ZMS Server will be listening on port 4443.
Stop the ZMS Server by executing:
$ cd athenz-zms-X.Y $ bin/zms stop