Setup Athenz UI¶
- Getting Software
- Server Configuration Setup
- Development Environment
- Production Environment
- Start/Stop UI Server
- UI Access
The following tools are required to be installed on hosts configured to run UI server.
UI Server is a Node.js 14.x application.
Verify that you have the following versions of
nodemon binaries installed on your system and are included
in your runtime path:
$ node --version v14.18.2 $ npm -v 8.3.0 $ npm install -g nodemon $ nodemon --version 2.0.15
Build the latest UI binary release by following the
development instructions. The binary release
packages will be created automatically in the
athenz-ui-X.Y-bin.tar.gz to your desired setup directory.
$ tar xvfz athenz-ui-X.Y-bin.tar.gz $ cd athenz-ui-X.Y
Server Configuration Setup¶
To run UI Server, the system administrator must generate the keys,
certificates and make necessary changes to the configuration settings.
For our configuration script we need the ZMS server hostname and a
copy of the server certificate file since ZMS Server is
running with a self-signed certificate. From your ZMS Server
installation, copy the
zms_cert.pem file from the
athenz-zms-X.Y/var/zms_server/certs directory to a local directory on the
host that will be running the UI Server. For the
argument below pass the full path of the zms_cert.pem. For the
argument below pass the system admin that the zms server configured with:
user.john and the
admin-fullname is the full name for the administrator:
$ cd athenz-ui-X.Y $ bin/setup_dev_ui.sh <zms-hostname> <zms-public-cert-path> <admin-username> <admin-fullname>
Running this setup script completes the following tasks:
- Generate a unique public/private key pair that UI Server will use to sign user's authorized service tokens. The UI has already been authorized to be allowed to carry out the users' requested operations.
- Generate a self-signed X509 certificate for UI Server HTTPS support
- Create a new domain called athenz and register the ui service in that domain
Private/Public Key Pair¶
Generate a unique private/public key pair that UI Server will use
to sign user's authorized service tokens. The UI has already been
authorized to be allowed to carry out the users' requested
operations. From the
athenz-ui-X.Y directory execute the following
$ cd keys $ openssl genrsa -out athenz.ui-server.pem 2048 $ openssl rsa -in athenz.ui-server.pem -pubout > athenz.ui-server_pub.pem
Server X509 Certificate¶
For Athenz UI production server it is strongly recommended purchasing a certificate for HTTPS access from a well known certificate authority.
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 name your UI
server private key as
ui_key.pem and the X509 certificate
ui_cert.pem and copy those files into the
Register UI Service¶
In order for UI 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
$ cd athenz-ui-X.Y $ bin/<platform>/zms-cli -z https://<zms-server>:4443/zms/v1 add-domain athenz $ bin/<platform>/zms-cli -z https://<zms-server>:4443/zms/v1 -d athenz add-service ui-server 0 keys/athenz.ui-server_pub.pem
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-ui-X.Y $ bin/<platform>/athenz-conf -o config/athenz.conf -z https://<zms-server>:4443/
Start/Stop UI Server¶
Set the following environment variable before starting the UI Server:
$ cd athenz-ui-X.Y $ export UI_SERVER=<ui-server-host-name> ZMS_SERVER=<zms-server-host-name> $ sudo -E bin/athenz_ui start
Based on the sample configuration file provided, Athenz UI Server will be listening on port 443.
To stop the UI server, execute the following commands:
$ cd athenz-ui-X.Y $ export UI_SERVER=<ui-server-host-name> ZMS_SERVER=<zms-server-host-name> $ sudo -E bin/athenz_ui stop
To access Athenz UI in your browser, visit:
Development Environment Restrictions¶
Since the development setup is using self-signed X509 certificates for Athenz ZMS and UI servers, the administrator must add exceptions when accessing Athenz UI or install the self-signed certificates for those two servers into his/her own web browser.
The administrator must first access the ZMS Server endpoint in the browser to accept the exception since the Athenz UI contacts ZMS Server to get an authorized token for the user when logging in. The administrator must access:
first and accept the certificate exception before accessing Athenz UI.
Alternatively, the administrator may decide to install the self-signed
certificates for the ZMS and UI servers in their browser. For ZMS Server,
the self-signed certificate is called
zms_cert.pem and this file
is located in the
For UI Server, the self-signed certificate is called
ui_cert.pem and this file
is located in the