2. ID Broker Installation#

The ID Broker setup consists of four nodes:

A Primary Directory Node which allows running of Backup Nodes.
A Backup Directory Node providing the REST API for school authorities (the Provisioning API).
A Backup Directory Node providing the REST API for service providers (the Self-disclosure API).
A Backup Directory Node running the Self-disclosure DB Builder (a.k.a. SDDB).
A Backup Directory Node running the SSO Broker (implemented with keycloak).

The installation on separate nodes is done for better security and scaling. Everything could be installed on just one node, but we don’t recommend it.

Also, for performance reasons, the Primary Directory Node will not run any exposed services.

2.1. Primary#

Note

This step has to be fully finished before continuing with the installation of the Backup Directory Nodes. If the Backup Directory Nodes join the Primary Directory Node’s domain, the required packages for UCS@school will then be automatically installed.

Install a UCS 5.0-4 Primary Directory Node according to normal procedure

Install UCS@school app:

USERNAME=Administrator
PASSWORD=univention
SCHOOLNAME=school1
SCHOOLINSTALLER_PATH=/tmp/schoolinstaller.py

univention-app install ucsschool
curl https://raw.githubusercontent.com/univention/univention-corporate-server/5.0-4/test/utils/schoolinstaller.py \
    --output "$SCHOOLINSTALLER_PATH"
python3 "$SCHOOLINSTALLER_PATH" -M -u "$USERNAME" -p "$PASSWORD" -o "$SCHOOLNAME"

Install UCS@school Kelvin REST API app:

USERNAME=Administrator
PASSWORD=univention
PASSWORD_FILE=/tmp/password.txt
echo "$PASSWORD" > "$PASSWORD_FILE"

univention-app install --username "$USERNAME" --pwdfile "$PASSWORD_FILE" ucsschool-kelvin-rest-api

Install the LDAP schemas, ACLs and extended attributes. This will create LDAP indices, which will take a lot of time. The number of processes the UDM REST API and Kelvin REST API start will be set to the number of available CPUs:
```
echo 'deb https://USERNAME:PASSWORD@service.software-univention.de/apt/00342/ ucs_5.0-0-id-broker/all/' >> \
    /etc/apt/sources.list.d/40_id-broker.list
univention-install -y id-broker-primary
```
Check that the installation works
- Check that the kelvin installation works and the extended UDM properties are exposed by Kelvin:
```
curl -i -k -X POST https://$(hostname -f)/ucsschool/kelvin/token \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "username=Administrator" \
-d "password=<Administrator password>"
```
- Look for a message about UDM mapping configuration that should contain school=['entryUUID', 'idBrokerPseudonym0001' and so on in /var/log/univention/ucsschool-kelvin-rest-api/http.log.

2.2. Backup - Self-disclosure API#

Note

Please make sure that the installation of the Primary Directory Node is finished, before continuing with this step.

Note

As of August 2023 the Self-Disclosure API needs a Redis database and a Backup - Univention ID Broker Self-disclosure DB Builder to be fully functional (cf. step five in the list below).

Install a UCS 5.0-4 Backup Directory Node, and have it join the domain of the Primary Directory Node.
Prepare to run the Self-disclosure plugin joinscript. Set the following variable that contains the OAuth2 settings for the Keycloak IdP: export DISCLOSURE_IDP_CONFIG_VALUE='{"strategy": "oauth2", "settings": {"jwk_url": "URL", "issuer": "ISSUER", "audience": "AUDIENCE"}}', where
- URL is the URL to the Keycloaks JWK endpoint. This is typically https://FQDN/auth/realms/$REALM_NAME/protocol/openid-connect/certs
- ISSUER is the string identifying the tokens issuer. The value is set in Keycloak by default as https://FQDN/auth/$REALM_NAME.
- AUDIENCE is a string that identifies this API as the valid consumer of the access token. The value for AUDIENCE has to be configured in Keycloak as the aud value of the access token.

Install UCS@school APIs app (using the variables from the previous steps):

univention-app install --username "$USERNAME" --pwdfile "$PASSWORD_FILE" ucsschool-apis

Install the self-disclosure plugin for the “UCS@school APIs” app:

echo 'deb https://USERNAME:PASSWORD@service.software-univention.de/apt/00342/ ucs_5.0-0-id-broker/all/' >> \
    /etc/apt/sources.list.d/40_id-broker.list
univention-install -y id-broker-self-disclosure-api-plugin

Set redis_url and sddb_rest_host in /etc/ucsschool/apis/id-broker/self-disclosure-api.json (see Backup - Univention ID Broker Self-disclosure DB Builder):
```
{
    "redis_url": "redis://$IP_OF_REDIS_INSTANCE:6379",
    "sddb_rest_host": "$FQDN_OF_SDDB_BUILDER_API"
}
```
Check that the installation works
- look for a message confirming that plugins are enabled in /var/log/univention/ucsschool-apis/http.log:
```
Plugins enabled in settings: ['auth', 'idbroker-common', 'self_disclosure']
```
- check that the Swagger UI works and the Self-disclosure API resources exist - Visit https://FQDN/ucsschool/apis/docs/
- if the above doesn’t work, check the docker logs for error messages:
```
docker logs $(ucr get appcenter/apps/ucsschool-apis/container)
```
- also note that the status of the docker container can be checked with:
```
systemctl status docker-app-ucsschool-apis.service
```
The Self-disclosure API should be configured in a way that can only be accessed by services which have been registered (see Registration of a new service provider).

2.3. Backup - Provisioning API#

Note

Please make sure that the installation of the Primary Directory Node is finished, before continuing with this step.

Install a UCS 5.0-4 Backup Directory Node, and have it join the domain of the Primary Directory Node.

Install UCS@school Kelvin REST API app and set the number it’s processes to the number of available CPUs:

USERNAME=Administrator
PASSWORD=univention
PASSWORD_FILE=/tmp/password.txt
echo "$PASSWORD" > "$PASSWORD_FILE"

univention-app install --username "$USERNAME" --pwdfile "$PASSWORD_FILE" ucsschool-kelvin-rest-api

Install UCS@school APIs app (using the variables from the last step):

univention-app install --username "$USERNAME" --pwdfile "$PASSWORD_FILE" ucsschool-apis

Install the provisioning plugin for the “UCS@school APIs” app:

echo 'deb https://USERNAME:PASSWORD@service.software-univention.de/apt/00342/ ucs_5.0-0-id-broker/all/' >> \
    /etc/apt/sources.list.d/40_id-broker.list
univention-install -y id-broker-provisioning-api-plugin

Check that the installation works

check that the kelvin installation works and the APIs have access to kelvin:

KELVIN_USER="$(python -c 'import json; \
   print(json.load(open("/etc/ucsschool/apis/id-broker/provisioning-api.json"))["username"])')"
KELVIN_PASSWORD="$(python -c 'import json; \
   print(json.load(open("/etc/ucsschool/apis/id-broker/provisioning-api.json"))["password"])')"

curl -i -k -X POST https://$(hostname -f)/ucsschool/kelvin/token \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "username=$KELVIN_USER" \
-d "password=$KELVIN_PASSWORD"

look for a message confirming that plugins are enabled in /var/log/univention/ucsschool-apis/http.log:
```
Plugins enabled in settings: ['auth', 'idbroker-common', 'provisioning']
```
check that the Swagger UI works and the provisioning resources exists - Visit https://FQDN/ucsschool/apis/docs/
if the above doesn’t work, check the docker logs for error messages:
```
docker logs $(ucr get appcenter/apps/ucsschool-apis/container)
```
also note that the status of the docker container can be checked with:
```
systemctl status docker-app-ucsschool-apis.service
```

Create at least one service provider mapping by using the tool manage-service-providers. See Service provider mapping and secrets.
The Provisioning API should be configured in a way that can only be accessed by school authorities which have been registered (see Add a new school authority).

2.4. Backup - Univention ID Broker Self-disclosure DB Builder#

The Univention ID Broker Self-disclosure DB Builder (SDDB) improves the response times of the Backup - Self-disclosure API. For that it transforms LDAP and Kelvin data in a Redis database.

Install the database on a separate server. This documentation references it’s IP address during the installation with $IP_OF_REDIS_INSTANCE.

The section Univention ID Broker Self-disclosure DB Builder describes the components used by the administrator.

2.4.1. SDDB Installation#

Note

Make sure that the installation of the Primary Directory Node is complete, before continuing with this step.

Install a UCS 5.0-4 Backup Directory Node and join it into the domain of the Primary Directory Node.

Install the app UCS@school Kelvin REST API and set the number of its processes to the number of available CPUs:

$ USERNAME=Administrator
$ PASSWORD=univention
$ PASSWORD_FILE=/tmp/password.txt
$ echo "$PASSWORD" > "$PASSWORD_FILE"

$ univention-app install \
  --username "$USERNAME" \
  --pwdfile "$PASSWORD_FILE" \
  ucsschool-kelvin-rest-api

Install the app SDDB:

$ univention-app install \
   --username "$USERNAME" \
   --pwdfile "$PASSWORD_FILE" \
   id-broker-sddb-builder

Configure the app SDDB:

$ univention-app configure \
   id-broker-sddb-builder \
   kelvin_host="$(hostname -f)" \
   db_url="redis://$IP_OF_REDIS_INSTANCE:6379" \
   kelvin_username="$ID_BROKER_SDDB_BUILDER_HOSTDN" \
   kelvin_password="$ID_BROKER_SDDB_BUILDER_HOSTDN_PASSWORD" \
   converter_daemon_num_workers=24

Verify, that everything works:
1. The SDDB Command line interface connection tests mustn’t yield errors:
```
$ univention-app shell \
   id-broker-sddb-builder \
   sddb-builder \
   connection-tests
```
2. The following log files /var/log/univention/id-broker-sddb-builder/ don’t contain errors. Alternatively you can use the following command:
```
docker logs $(ucr appcenter/apps/id-broker-sddb-builder/container)
```
3. The Swagger UI of the SDDB REST API is available at https://FQDN/ucsschool/id-broker-sddb-builder/v1/.

2.5. Backup - SSO Service - Keycloak#

Ansible scripts to install Keycloak are supplied in this repository. See the Keycloak folder.

Install Ansible, this does not need to be done on a node in the domain. That will be the Ansible control node. It needs ssh access to the Backup Directory Node on which Keycloak will be installed. The Backup Directory Node will be the Ansible managed node. Tested with Ansible >= 2.10.8. Older versions might be missing some collections. If the controller is a UCS node, an up to date version can be installed through pip.
Switch into the Keycloak folder in this repository.
Edit the address in the hosts.ini to let the Keycloak host point to this Backup Directory Node. See the hosts.ini.example file.
Create a X509 Certificate for signatures (id-broker.key and id-broker.cert are expected). The private key is used to sign authentication request from Keycloak to a school IdP. Keep this key secure to be able to redeploy Keycloak without having to reconfigure all connected schools. The certificate and key can be created for example as follows:
```
$ openssl req -new -newkey rsa:4096 \
> -days 365 -nodes -x509 \
> -subj "/CN=id-broker" \
> -keyout id-broker.key \
> -out id-broker.cert
```
Make sure the Ansible control node has full ssh access to the Backup Directory Node. E.g.:
```
$ ssh-copy-id -i ~/.ssh-keys/id_rsa.pub root@$BACKUP_KEYCLOAK
```
Create at least one new school authority within the ID Broker.

To create a school authority, see Add a new school authority. Please jump over to this chapter, perform the described steps, and then continue here.
Configure at least one new service provider within the ID Broker.

The necessary steps to create a new service provider are explained to you in this chapter. Please jump over to this chapter, perform the described steps, and then continue here.
Run Ansible to install Keycloak:

ansible-playbook -i hosts.ini main.yml

2.6. All - Performance settings and optimizations#

2.6.1. OpenLDAP and UCS directory listener database size#

Both the OpenLDAP server and the UCS directory listener use the MDB database backend with a fixed maximum size (bytes). Once this maximum size is reached write operations to the databases are no longer possible.

Depending on the excepted number of user accounts on the ID Broker systems the value for this maximum size has to be changed.

We recommend to start with the following settings (50G):

$ ucr set ldap/database/mdb/maxsize=50000000000 && service slapd restart
$ ucr set listener/cache/mdb/maxsize=50000000000 && service univention-directory-listener restart

These settings can be changed any time and are applied immediately after restarting the services.

2.6.2. Disable non-essential services#

For performance optimizations some services can be disabled on the UCS systems in the ID Broker domain.

Deactivate expensive updates of the NSS and the portal group cache and add regular portal group updates at night:

ucr set \
    listener/module/portal_groups/deactivate=yes \
    nss/group/cachefile/invalidate_on_changes=no \
    cron/portal_groups/command='/usr/sbin/univention-portal update --reason ldap:group' \
    cron/portal_groups/time='30 4 * * *' \
    cron/portal_groups/description='Update UCS portal group cache.'

systemctl restart univention-directory-listener.service

ID Broker operations manual

ID Broker Installation

Contents

2. ID Broker Installation#

2.1. Primary#

2.2. Backup - Self-disclosure API#

2.3. Backup - Provisioning API#

2.4. Backup - Univention ID Broker Self-disclosure DB Builder#

2.4.1. SDDB Installation#

2.5. Backup - SSO Service - Keycloak#

2.6. All - Performance settings and optimizations#

2.6.1. OpenLDAP and UCS directory listener database size#

2.6.2. Disable non-essential services#