Activate#

To activate single sign-on through SAML, use the following steps:

1. Ensure that all users in your domain who want to use the portal and the UCS management system with single sign-on can reach ucs-sso.[Domain Name].

2. Change the Univention Configuration Registry Variable portal/auth-mode to saml with ucr set. The default value was ucs.

3. For the change to take effect, restart the portal server with the following command:

   $ systemctl restart univention-portal-server.service
   

Update sign-in links#

Restarting the portal server automatically updates the Login link in the user menu. You must manually update the portal tile. The default portal has a preconfigured 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:

1. In Univention Management Console open the UMC Module Portal: Domain ‣ Portal.

2. To activate the preconfigured sign in tile for SAML, edit the entry login-saml, scroll down to the section Advanced and activate the checkbox Advanced.

3. To deactivate the default sign in tile, edit the entry login-ucs, scroll down to the section Advanced and deactivate the checkbox Advanced.

To change back to the default sign-in in UCS without single sign-on, you need to revert the steps for updating the portal tile and set the UCR variable portal/auth-mode to ucs.

Requirements#

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

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

   For information about how to upgrade, refer to Updates of UCS systems.

2. You must have the app Keycloak installed in your UCS domain.

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

Activation#

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.

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

   Change the Univention Configuration Registry Variable umc/web/oidc/enabled to true with ucr set.

   $ ucr set \
      umc/web/sso/enabled=false \
      umc/web/oidc/enabled=true
   

2. Run the join script for the UMC web server:

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

3. Change the Univention Configuration Registry Variable portal/auth-mode to oidc with ucr set. The default value was ucs.

4. For the change to take effect, restart the portal server with the following command:

   $ systemctl restart univention-portal-server.service
   

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 Primary Directory Node with the commands in Listing 4.1.

$ 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)"

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 UMC module, such as Users, and perform a search.

You find relevant logging information in the following locations:

• 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 with SAML for single sign-on. The link must point to /univention/oidc/.

Deactivate#

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

1. Unset the Univention Configuration Registry Variable umc/web/oidc/enabled with ucr unset:

   $ ucr unset umc/web/oidc/enabled
   

2. Remove the OIDC RP from Keycloak with the following command:

   $ univention-keycloak oidc/rp remove \
      "$(ucr get umc/oidc/$(hostname -f)/client-id)"
   

3. Unset all Univention Configuration Registry Variables that you can find with the following searches:

   $ ucr search --brief --key ^umc/oidc
   $ ucr search --brief --key ^ldap/server/sasl/oauthbearer
   

4. Remove the OIDC secret from the system and restart affected services:

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

5. Manually update the portal tile for Login, so that the link points to /univention/login/.

6. Change the Univention Configuration Registry Variable portal/auth-mode to ucs with ucr set and restart the portal server.

Identity Provider with non-standard FQDN#

By default, the FQDN for the Keycloak identity provider is ucs-sso-ng.$domainname. However, it’s possible to configure a different FQDN for the identity provider. For more information, see Configuration of the identity provider in Univention Keycloak app documentation [4].

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 Univention Configuration Registry 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.2.

$ 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

Non-standard FQDN for the Univention Portal and UMC#

By default, the UMC is available under the FQDN $hostname.$domainname. If you have a setup with a different FQDN for the UMC you have to change the Univention Configuration Registry Variable umc/oidc/rp/server to the FQDN of the UMC, and run the join script of the UMC web server again, as shown in Listing 4.3.

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

Back-channel sign-out#

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

If you have only one UMC server without UMC multiprocessing, you don’t need to change the configuration.

To keep track of the sessions in the database for UMC, you need to configure the database connection string with the univention-mangement-console-settings script, as shown in Listing 4.5.

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

1. PostgreSQL database server:

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

   Or you install and configure PostgreSQL on one of the UCS servers. As shown in the example in Listing 4.4, you can freely choose the values for db_user, db_name, and db_password. db_host is the UCS system with PostgreSQL running.

   Listing 4.4 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'\""
   $ ucr set postgres11/pg_hba/config/host="db_name db_user 0.0.0.0/0 md5"
   $ systemctl restart postgresql
   

2. Set the SQL connection URI on the Primary Directory Node:

   Listing 4.5 Set SQL connection URI#

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

3. Optional parameters for the database connection pool:

   • Pool Size: The number of connections to the database. The default value is 5.

   • Max Overflow: The maximum number of temporary connections. The default value is 10.

   • Pool Timeout: The number of seconds to wait for a connection to be available. The default value is 30.

   • Pool Recycle: The number of seconds after which a connection is recycled. The default value is -1.

   With these default values, each UMC process can have up to 15 connections to the database. The total number of connections is: <Number of Servers> * <Number of Processes> * (<Pool Size> + <Max Overflow>). Make sure that the database can handle the number of connections.

   Listing 4.6 Set optional parameters for the database connection pool#

   $ univention-management-console-settings set \
        -s 5 \
        -o 10 \
        -t 30 \
        -r 3600
   

4. Restart the UMC on all UCS servers:

   $ systemctl restart univention-management-console-server