3. Installation

This section is for Guardian administrators and covers the installation of the Guardian on UCS systems. If you’re upgrading the Guardian to a new version, refer to the upgrade guide Upgrading the Guardian.

3.1. Installation on a UCS Primary Directory Node

This section describes the installation of the Guardian on a Primary Directory Node. For other server roles, see Installation on various UCS server roles.

Guardian administrators install the different components of the Guardian from the Univention App Center. A prerequisite for using the Guardian is a working Keycloak installation in the UCS domain. For information about how to install and configure Keycloak in a UCS, refer to Installation of Keycloak app.

To install all required components on a UCS primary node, run the following command:

Listing 3.1 Install Guardian apps from command line

$ univention-app install \
    guardian-management-api \
    guardian-authorization-api \
    guardian-management-ui

To use the Guardian Management UI, it’s also necessary to give the user the required permissions. For this step the Management UI already utilizes the Guardian. The user needs to get the proper guardianRole assigned. The Administrator user gets this roles automatically assigned during the app installation. To make a user account the Guardian super user, who has all privileges, run the following command:

Listing 3.2 Assign Guardian super user role to a user

$ udm users/user modify \
   --dn "$USER_DN" \
   --set guardianRole=guardian:builtin:super-admin

You have completed the Guardian setup. You can reach the Management UI from the Univention Portal.

3.2. Upgrading the Guardian

For minor and patch level version changes, use the command univention-app upgrade:

Listing 3.3 Install Guardian apps from command line

$ univention-app upgrade \
    guardian-management-api \
    guardian-authorization-api \
    guardian-management-ui
$ univention-app restart guardian-management-api
$ univention-app restart guardian-authorization-api

3.2.1. Upgrading from major version 1

Use the command univention-app upgrade to upgrade the Guardian:

Listing 3.4 Install Guardian apps from command line

$ univention-app upgrade \
    guardian-management-api \
    guardian-authorization-api \
    guardian-management-ui

The previous major version used a different Keycloak client for the Management API, so the secret file for the client must be updated. Obtain the KEYCLOAK_SECRET for the new client with the following command, using the server where Keycloak is installed:

Listing 3.5 Retrieve KEYCLOAK_SECRET

$ KEYCLOAK_SECRET=$(univention-keycloak \
   oidc/rp secret \
   --client-name guardian-management-api \
   | sed -n 2p \
   | sed "s/.*'value': '\([[:alnum:]]*\)'.*/\1/")

On the server where the Management API is located:

Listing 3.6 Write KEYCLOAK_SECRET to the machine-to-machine secret file

$ echo $KEYCLOAK_SECRET > /var/lib/univention-appcenter/apps/guardian-management-api/conf/m2m.secret
$ chmod 600 /var/lib/univention-appcenter/apps/guardian-management-api/conf/m2m.secret

If you are unsure whether the Guardian was set up correctly during the previous installation, follow the configuration steps described in Installation on a UCS Primary Directory Node to complete the upgrade. Otherwise, the only additionally needed configuration steps are:

Listing 3.7 Additional configure and restart step

$ univention-app configure guardian-authorization-api
$ univention-app restart guardian-authorization-api
$ univention-app configure guardian-management-api
$ univention-app restart guardian-management-api

3.3. Installation on various UCS server roles

This setup assumes that you have all Guardian components installed on the same UCS system, and that Keycloak and the UDM REST API are also running on that system. This system is usually the Primary Directory Node.

The Guardian supports the installation of the Management API on any UCS server role, as well as the distribution of the individual components on different systems. For this to work, however, you must manually configure several settings regarding URLs for Keycloak, the UDM REST API, and the various Guardian components themselves. For a full reference of all the app settings, refer to the section Configuration. The installation of the Authorization API is restricted to the UCS server role Primary Directory Node and Backup Directory Node.

3.4. Load balancing and multiple instances

A design goal for the Guardian was the ability to run multiple instances of each component. It’s possible to deploy multiple instances of the Guardian Management UI and Guardian Authorization API apps in the UCS domain with no known issues, as long as they’re configured properly.

Only deploy the Management API once in each UCS domain due to the limitations mentioned in App Center database limitations.