Authentication

4.1. Authentication#

This page covers configuration aspects around authentication in Nubus for UCS for technical administrators. For a general description, see Authentication in Nubus Manual 1.x [4].

4.1.1. Sign-in#

For a general description of sign-in, see Sign-in in Nubus Manual 1.x [4]. This section covers settings and peculiarities for Nubus for UCS.

4.1.1.1. Choose the right user account#

To sign in, enter the Username and Password of the corresponding domain account in the login mask.

Administrator

For the general description, see Administrator in Nubus Manual 1.x [4]. For a specific description of Nubus for UCS, continue reading.

When you sign in on a UCS Primary Directory Node or UCS Backup Directory Node, the Management UI shows the management modules for the administration and configuration of the local system as well as the modules for the administration of data in the domain.

You specified the initial password for the Administrator account in the setup wizard during installation. The password corresponds to the initial password of the local root account. Use the Administrator account for the initial sign-in at a newly installed UCS Primary Directory Node.

4.1.1.2. Change Nubus web session timeout#

You can change the timeout of the Nubus web session through the UCR variable umc/http/session/timeout.

4.1.2. Refresh browser tabs on sign-out#

For a general description of sign-out, see Sign-out in Nubus Manual 1.x [4].

After detecting a sign-out, Nubus automatically refreshes all browser tabs with an active Portal session.

You can prevent Nubus from reloading the browser tabs upon sign-out. Set the UCR variable portal/reload-tabs-on-logout to the value true. The default value is false.

4.1.3. Single sign-on#

For a general description of single sign-on, see Single sign-on in Nubus Manual 1.x [4].

The default configuration in Nubus for UCS has single sign-on deactivated. After you install the Keycloak app, Nubus for UCS uses SAML.

4.1.3.1. SAML configuration for single sign-on#

UCS supports single sign-on through SAML using the Keycloak app. Refer to Use Keycloak for login to Univention Portal in Univention Keycloak app documentation [6].

4.1.3.1.1. Activate SAML for single sign-on#

After completing the configuration for Keycloak, use the following steps for a better user experience:

Ensure that all users in your domain who want to use the Portal and the Management UI with single sign-on can reach ucs-sso-ng.[Domain Name].
Change the UCR variable portal/auth-mode to saml with the command in Listing 4.1.
Listing 4.1 Set Portal authentication mode to SAML#
```
$ ucr set portal/auth-mode="saml"
```
To apply the configuration, restart the Portal server on every UCS node with the command in Listing 4.2.
Listing 4.2 Restart Portal service#
```
$ systemctl restart univention-portal-server.service
```

4.1.3.1.2. Update the default login tile in the Portal#

Restarting the Portal server automatically updates the Login link in the user menu. However, you need to manually update the portal tile for the Login to use SAML. The default portal has a preconfigured but deactivated single sign-on login tile. Use the portal edit mode to enable it.

To replace the Login tile with the single sign-on tile, follow these steps:

In the Management UI, open the Portal management module through Domain ‣ Portal.
To activate the preconfigured sign-in tile for SAML, edit the entry login-saml, scroll down to the section Advanced, and activate the checkbox Activated.
To deactivate the default sign-in tile, edit the entry login-ucs, scroll down to the section Advanced, and deactivate the checkbox Activated.

4.1.3.1.3. Restore login without single sign-on#

To change back to the default sign-in in Nubus for UCS without single sign-on, use the following steps:

Revert the steps in Update the default login tile in the Portal.
Set the UCR variable portal/auth-mode to the value ucs in Activate SAML for single sign-on.

4.1.3.2. OpenID Connect for single sign-on#

OpenID Connect (OIDC) is a protocol that allows single sign-on. OIDC is a more lightweight protocol than SAML. It’s one variant for using single sign-on in the Portal and the UCS management system. This section describes how to use it with UCS.

Before you can use OIDC for single sign-on, you must meet the following requirements:

You must at least have UCS 5.0 erratum 1118 installed throughout your Nubus for UCS domain.

For information about how to upgrade, refer to Updates of UCS systems in Univention Corporate Server - Manual for users and administrators [3].
You must have the Keycloak app installed in your Nubus for UCS domain.

For information about the installation of Keycloak, refer to Installation in Univention Keycloak app documentation [6].

4.1.3.2.1. Activate OpenID Connect for single sign-on#

First, you need to decide on which UCS systems you want to enable single sign-on using OpenID Connect. Second, you need to apply the following steps to each of those UCS systems.

Deactivate SAML for Portal sign-in through the UCR variable umc/web/sso/enabled so that the automatic sign-in doesn’t try SAML first, but instead uses OIDC directly.

Change the UCR variable umc/web/oidc/enabled to true with the command in Listing 4.3.
Listing 4.3 Activate OpenID Connect and deactivate SAML#
```
$ ucr set \
   umc/web/sso/enabled=false \
   umc/web/oidc/enabled=true
```

Run the join script for the UMC web server with the command in Listing 4.4.

Listing 4.4 Run join script for the UMC web server#

$ univention-run-join-scripts \
   --force \
   --run-scripts \
   92univention-management-console-web-server.inst

Change the UCR variable portal/auth-mode to oidc with the command in Listing 4.5. The default value is ucs.
Listing 4.5 Set Portal authentication mode to OIDC#
```
$ ucr set portal/auth-mode="oidc"
```
To apply the configuration, restart the Portal Server on every UCS node with the command in Listing 4.2.

4.1.3.2.2. Create sign-in links#

Restarting the Portal Server automatically updates the Login link in the user menu. You can optionally create a portal tile for the sign-in with OpenID Connect on the UCS Primary Directory Node with the commands in Listing 4.6.

Listing 4.6 Create portal tile for sign-in with OpenID Connect#

$ udm portals/entry create --ignore_exists \
    --position "cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
    --set name=login-oidc \
    --append displayName="\"en_US\" \"Login (Single sign-on)\"" \
    --append displayName="\"de_DE\" \"Anmelden (Single Sign-on)\"" \
    --append description="\"en_US\" \"Log in to the portal\"" \
    --append description="\"de_DE\" \"Am Portal anmelden\"" \
    --append link='"en_US" "/univention/oidc/?location=/univention/portal/"' \
    --set anonymous=TRUE \
    --set activated=TRUE \
    --set linkTarget=samewindow \
    --set icon="$(base64 /usr/share/univention-portal/login.svg)"

$ udm portals/category modify --ignore_exists \
    --dn "cn=domain-service,cn=category,cn=portals,cn=univention,$(ucr get ldap/base)"\
    --append entries="cn=login-oidc,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)"

4.1.3.2.3. Verification and log files#

To verify that the setup works, open the URL https://FQDN/univention/oidc/ in a web browser, such as Mozilla Firefox, and sign in. Open a management module, such as Users module, and perform a search.

You can find relevant logging information in the following locations on the UCS system:

Log file: /var/log/univention/management-console.server.log
journald: journalctl -u slapd.service

To reflect the changes for the login method in the Portal, you need to edit the Login tile manually, similar to the setup described in SAML configuration for single sign-on. The link must point to /univention/oidc/.

4.1.3.2.4. Deactivate OpenID Connect for single sign-on#

First, you need to decide on which Nubus for UCS node you want to deactivate single sign-on using OpenID Connect. Second, you need to apply the following steps to each of those nodes.

Unset the UCR variable umc/web/oidc/enabled with the command in Listing 4.7.
Listing 4.7 Unset umc/web/oidc/enabled#
```
$ ucr unset umc/web/oidc/enabled
```
Remove the OIDC RP from Keycloak with the command in Listing 4.8.
Listing 4.8 Remove the OIDC RP from Keycloak#
```
$ univention-keycloak oidc/rp remove \
   "$(ucr get umc/oidc/$(hostname -f)/client-id)"
```
Unset all UCR variables that you find using the commands in Listing 4.9.
Listing 4.9 Search for UCR variables to unset#
```
$ ucr search --brief --key ^umc/oidc
$ ucr search --brief --key ^ldap/server/sasl/oauthbearer
```

Remove the OIDC secret from the system and restart affected services with the commands in Listing 4.10.

Listing 4.10 Remove OIDC secret#

$ rm -f \
   /etc/umc-oidc.secret \
   /usr/share/univention-management-console/oidc/http*
$ systemctl restart slapd univention-management-console-server

Manually update the portal tile for Login, so that the link points to /univention/login/.
Change the UCR variable portal/auth-mode to ucs and restart the Portal Server. For details, see Restore login without single sign-on.

4.1.3.2.5. Identity provider with non-standard FQDN#

By default, the FQDN for the Keycloak identity provider is ucs-sso-ng.$domainname. However, you can configure a different FQDN for the identity provider. For more information, see Configuration of the identity provider in Univention Keycloak app documentation [6].

If you have such a setup, you have to configure the identity provider for the OpenID Connect authentication in UMC on each UCS system. Change the UCR variable umc/oidc/issuer to the FQDN of your Keycloak identity provider and run the join script of the UMC web server again, as shown in Listing 4.11.

Listing 4.11 Set non-standard FQDN for identity provider Keycloak#

$ IDP="auth.extern.test"
$ ucr set umc/oidc/issuer="https://$IDP/realms/ucs"
$ univention-run-join-scripts --force \
   --run-scripts 92univention-management-console-web-server

4.1.3.2.6. Non-standard FQDN for the Univention Portal and Management UI#

By default, the Management UI is available under the FQDN $hostname.$domainname. If you have a setup with a different FQDN for the Management UI, you have to change the UCR variable umc/oidc/rp/server to the FQDN of the Management UI, and run the join script of the UMC web server again, as shown in Listing 4.12.

Listing 4.12 Set non-standard FQDN for the Portal and Management UI#

$ ucr set umc/oidc/rp/server="portal.extern.test"
$ univention-run-join-scripts --force \
   --run-scripts 92univention-management-console-web-server
$ systemctl restart slapd

Important

If you want to run multiple Portal Servers or UMC Servers behind a load balancer, you need to run these commands on all Nubus for UCS nodes.

Since all the nodes use the same OIDC client in this setup, make sure that the file /etc/umc-oidc.secret has the same contents on each node and matches the client secret in Keycloak for that client.

4.1.3.2.7. Back-channel sign-out#

If you use OIDC back-channel sign-out together with multiprocessing of the Management UI, the Management UI needs a database for session storage to handle the session logout correctly. You have enabled multiprocessing in the Management UI if the UCR variable umc/http/processes has a value greater than one (> 1).

If you have only one UMC Server without UMC multiprocessing, you you can keep the configuration.

To keep track of the sessions in the database for the Management UI, you need to configure the database connection string with the univention-management-console-settings script, as shown in Listing 4.15.

However, if the Portal or the Management UI use multiple Nubus for UCS nodes for load balancing, or if the Management UI has a configuration for multiprocessing, it’s necessary to use a PostgreSQL database that all Nubus for UCS nodes can access. In these cases, you must consider the following aspects:

PostgreSQL database server:

You either need to provide a PostgreSQL database yourself that all the UMC Servers have access to.

Alternatively, you can install and configure PostgreSQL on one of the Nubus for UCS nodes. As shown in the example in Listing 4.13, you can freely choose the values for db_user, db_name, and db_password. db_host is a Nubus for UCS node with PostgreSQL running.

Listing 4.13 Example for installation of PostgreSQL#

$ univention-install univention-postgresql
$ su postgres -c "createdb db_name"
$ su postgres -c "/usr/bin/createuser db_user"
$ su postgres -c "psql db_name -c \"ALTER ROLE db_user WITH ENCRYPTED PASSWORD 'db_password'\""
$ su postgres -c "psql umc -c \"GRANT ALL ON SCHEMA public TO umc;\""
$ ucr set postgres15/pg_hba/config/host="umc umc 1x.2xx.0.0/16 md5"
$ systemctl restart postgresql

Set the SQL connection URI on the UCS Primary Directory Node, as shown in Listing 4.14.

Listing 4.14 Set SQL connection URI#

$ univention-management-console-settings set \
   -u 'postgresql+psycopg2://db_user:db_password@db_host:5432/db_name'

Optional parameters for the database connection pool:

Pool Size:

The number of connections to the database. Default value: 5.

Max Overflow:

The maximum number of temporary connections. Default value: 10.

Pool Timeout:

The number of seconds to wait for a connection to be available. Default value: 30.

Pool Recycle:

The number of seconds after which a connection is recycled. Default value: -1.

With these default values, each UMC process can have up to 15 connections to the database. The total number of connections is: $NumberOfServers \cdot NumberOfProcesses \cdot (PoolSize + MaxOverflow)$.

Make sure that the database can handle the number of connections. You can adjust these parameters as shown in Listing 4.15.
Listing 4.15 Set optional parameters for the database connection pool#
```
$ univention-management-console-settings set \
     -s 5 \
     -o 10 \
     -t 30 \
     -r 3600
```
Restart the UMC Server on all Nubus for UCS nodes with the command in Listing 4.16.
Listing 4.16 Restart UMC server#
```
$ systemctl restart univention-management-console-server
```