Setup ZMS (AuthoriZation Management System)¶
- 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.
Build the latest ZMS binary release by following the
development instructions. The binary release
packages will be created automatically in the
athenz-zms-X.Y-bin.tar.gz to your desired setup directory.
$ tar xvfz athenz-zms-X.Y-bin.tar.gz
To run ZMS Server, the system administrator must generate the keys and make necessary changes to the configuration settings.
$ cd athenz-zms-X.Y $ bin/setup_dev_zms.sh
Running this setup script completes the following two tasks:
- Generate a unique private key that ZMS Server will use to sign any NTokens it issues
- Generate a self-signed X509 certificate for ZMS Server HTTPS support
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:
- Run the process as root using sudo. This is only recommended for a local development installation.
- 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.
Checkout the Principal Authentication section for full details on authorities.
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 $ sudo -E bin/zms start
User Authentication section above regarding an alternative
solution of starting ZMS Server without using sudo.
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 $ sudo -E bin/zms stop