2. Installation#

2.1. Installation on a UCS primary node#

The different components of the Guardian can be installed from the Univention App Center. A prerequisite for using the Guardian is a working Keycloak installation in the UCS domain. How to install and configure Keycloak in a UCS domain can be found here.

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

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

Most of the settings are configured automatically, but since this is a preview version, some manual configuration steps remain.

KEYCLOAK_SECRET can be obtained by running the following command:

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

Update settings for the Management UI:

univention-app configure guardian-management-api --set \
    "guardian-management-api/oauth/keycloak-cli-client-secret=$KEYCLOAK_SECRET"

Then set your USERNAME and PASSWORD to credentials for a user which has access to the UDM REST API:

USERNAME=Administrator
PASSWORD=password

Then update settings for the Guardian Authorization API:

univention-app configure guardian-authorization-api --set \
    "guardian-authorization-api/udm_data/username=$USERNAME" \
    "guardian-authorization-api/udm_data/password=$PASSWORD"

To be able to use the Guardian Management UI, it is also necessary to give the user the required permissions. For this the Management UI already utilizes the Guardian. This means the user needs to get the proper guardianRole assigned. To make the Administrator account the Guardian super user, who has all privileges, execute:

udm users/user modify --dn uid=Administrator,cn=users,$(ucr get ldap/base) \
    --set guardianRole=guardian:builtin:super-admin

With these steps the Guardian setup is complete and the Management UI should be available from the Univention Portal.

2.1.1. Configuring Keycloak for join scripts#

When installing an app that uses the Guardian, it will need a special Keycloak client that is configured specifically for join scripts.

Run the following command on the server with the Guardian Management API installed:

GUARDIAN_SERVER="$(hostname).$(ucr get domainname)"
univention-keycloak oidc/rp create \
    --name guardian-scripts \
    --app-url https://$GUARDIAN_SERVER \
    --redirect-uri "https://$GUARDIAN_SERVER/univention/guardian/*" \
    --add-audience-mapper guardian-scripts

Then configure the new client using the Keycloak web interface. Choose ucs from the realm drop-down list at the top of the left navigation bar. Then click on Clients in the left navigation bar, and choose guardian-scripts.

Configure password login for scripts and remove the client secret:

  1. Go to the Settings tab.

  2. Navigate to the Capability config section.

  3. Turn Client authentication off.

  4. Under Authentication flow, check the checkbox for Direct access grants.

Click the Save button at the bottom of the screen.

Configure the correct audience for the Guardian:

  1. Go to the Client scopes tab.

  2. Click on guardian-scopes-dedicated.

  3. Choose Add mapper ‣ By configuration.

    1. Select Audience.

    2. For the Name, use guardian-audience.

    3. For the Included Client Audience, choose guardian.

  4. Choose Add mapper ‣ By configuration.

    1. Select User Attribute.

    2. For the Name, use dn.

    3. For the User Attribute, use LDAP_ENTRY_DN.

    4. For the Token Claim Name, use dn.

    5. Turn Add to ID Token off.

    6. Turn Add to userinfo off.

    7. Verify that Add to access token is on.

Click the Save button at the bottom of the screen.

2.2. Installation on different UCS server roles#

This setup assumes that all Guardian components are installed on the same host and that Keycloak as well as the UDM REST API are running on that host as well. This is usually the UCS primary node. The Guardian supports the installation of its components on any UCS server role as well as distributing the individual components on different hosts. For that to work though, multiple settings regarding URLs for Keycloak, the UDM REST API and the different Guardian components themselves have to be configured manually. Please check the chapter Configuration for a full reference of all the app settings.

2.3. Load balancing and multiple instances#

The Guardian was developed with the capability of running multiple instances of each component in mind. It is possible to deploy multiple instances of the Guardian Management UI and Guardian Authorization API apps in the UCS domain without any problems, as long as they are properly configured.

The Management API should only be deployed once in any UCS domain due to the limitations mentioned in App Center database limitations.