Reconfigure UCS Single Sign On

Reconfigure UCS Single Sign On

By default, UCS Single Sign On uses a shared DNS record to provide a failover for the Login.
The SAML Identity Provider is available at ucs-sso.domain.name, where domain.name is chosen during UCS installation.
Administrators often want to configure Single Sign On to be available from the internet.

As the UCS domain name is often chosen for an intranet scenario, service configuration has to be adapted to match the target domain- and hostnames.

Involved services

apache2

The default apache2 configuration uses a separate VirtualHost config to provide the Single Sign On for a specific FQDN, by default ucs-sso.domain.name, in univention-saml.conf.
Univention Management Console and the Portal run in a catch-all VirtualHost configuration in default.conf and default-ssl.conf.
The OpenID Connect provider by default runs in the scope of the UMC and the Portal, the apache2 configfile is openid-connect-provider.conf.

SAML identity provider

The UCS SAML identity provider is run via the separate VirtualHost config and can be reached separately from the rest of UCS components by a browser.
It is provided by simplesamlphp.
The SAML IdP runs on the DC Master and Backup servers in the UCS domain.
The SAML IdP shares the session state of logged in users accross all servers in the domain to support failover scenarios.
The most relevant option to change is the SAML entityID, a unique identifier for the IdP.
The entityID is commonly set to a URI at which the SAML IdP metadata for the provider can be accessed by service providers to support automatic configuration, e.g. https://ucs-sso.domain.name/simplesamlphp/saml2/idp/metadata.php.

OpenID Connect

The UCS OpenID Connect provider uses the SAML backend for authentication and authorization.
Configuring the URL where the provider can be accessed is done in the OIDC App setting, the default is ucs-sso.domain.name when installed on a DC Master or Backup.
Here, the URL to the SAML identity provider can also be set.
To connect other service to our OIDC IdP, the service has to be provided with

  • A shared client ID and a shared secret
  • Meta information about our provider. Usually, these are the communication endpoints that are available in a document, accessible via e.g. https://ucs-sso.domain.name/.well-known/openid-configuration

Univention Management Console / Portal

Login for the Portal uses the Univention Management Console backend on the same server.
To reconfigure either, the UMC configuration has to be adapted.
UMC / the Portal act as a SAML service provider in this scenario, authenticating against the UCS SAML identity provider.
It is currently not supported to configure a non-UCS identity provider
The SAML service provider metadata can be accessed at e.g. https://ucsserver.domain.name/univention/saml/metadata

Common scenarios

Configuring external DNS entries and network components that enable access to the UCS server from the internet, e.g. reverse proxies, is outside of the scope of this document.
For the all scenarios, it is important to setup DNS entries and reverse proxies before beginning to reconfigure UCS, as the steps require that access via external FQDNs is working.

Scenario 1, Portal and Single Sign On at different FQDNs

One common scenario in large environments is to have the Portal available at one FQDN, e.g. portal.internet.domain, and the Single Sign On at another, e.g. sso.internet.domain.
It takes a bit more effort in terms of configuration, but is more flexible in terms of adding failover or changing service offers later.
When configuring this scenario, it is encouraged to use two UCS servers or more for serving the different FQDNs, the configuration is much simpler.

Configure Identity Provider

On the server that should serve the Single Sign On, the configuration has to be adapted in the following way:

SSO_FQDN=sso.internet.domain

univention-certificate new -name "${SSO_FQDN}" -days 1825   # Due to a bug in the template we require for a certificate file to be present, even if it is not used
ucr set ucs/server/sso/fqdn="${SSO_FQDN}" \
        saml/idp/entityID="https://${SSO_FQDN}/simplesamlphp/saml2/idp/metadata.php" \
        ucs/server/sso/autoregistraton=no   # otherwise 91u-saml.inst will fail when trying to register a DNS entry for another domain

univention-run-join-scripts --force --run-scripts 91univention-saml.inst

In case UCS is directly exposed to the internet and must serve different HTTPS certificates, the following UCR variables can be set:

ucr set saml/apache2/ssl/certificate=<cert.file> \
        saml/apache2/ssl/key=<key.file> \
        saml/apache2/ssl/ca=<ca.file>
# optional, if required
ucr set saml/apache2/ssl/certificatechain=<chain.file>
service apache2 restart

Configure Univention Management Console and Portal

SSO_FQDN=sso.internet.domain
PORTAL_FQDN=portal.internet.domain

# On DC Master:
ssh "$(ucr get ldap/master)" univention-certificate new -name "${PORTAL_FQDN}" -days 1825
# copy certs to server where portal should run with the fqdn
scp -r "$(ucr get ldap/master)":/etc/univention/ssl/"${PORTAL_FQDN}"/ /etc/univention/ssl

ucr set ucs/server/sso/fqdn="${SSO_FQDN}" \
        umc/saml/sp-server="${PORTAL_FQDN}" \
        umc/saml/idp-server=https://${SSO_FQDN}/simplesamlphp/saml2/idp/metadata.php

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

Other UCS servers

On all other UCS servers in the domain, the following must be executed for Single Sign On to work with UMC

ucr set ucs/server/sso/fqdn="${SSO_FQDN}" \
        umc/saml/idp-server=https://${SSO_FQDN}/simplesamlphp/saml2/idp/metadata.php
univention-run-join-scripts --force --run-scripts 92univention-management-console-web-server.inst

To have working Single Sign On work for new UCS servers in the domain, a UCR policy should be configured and assigned to servers before installation, which sets ucs/server/sso/fqdn to the correct FQDN.

Scenario 2, Portal and Single Sign On at the same FQDN

Another common scenario is to have one FQDN which serves the portal and Login at the same FQDN, e.g. login.internet.domain.
This keeps things simpler in terms of required DNS and certificate handling, but is not as flexible if the services should be spread over several servers later.

Reconfigure SAML IdP and UMC / Portal

FQDN=login.internet.domain

ucr set ucs/server/sso/autoregistraton=no \
        saml/idp/entityID="https://${FQDN}/simplesamlphp/saml2/idp/metadata.php" \
        ucs/server/sso/fqdn=$FQDN \
        umc/saml/sp-server=$FQDN \
        ucs/server/sso/virtualhost=false \

echo "ServerName $FQDN" >>/etc/apache2/ucs-sites.conf.d/servername.conf

univention-run-join-scripts --force --run-scripts 91univention-saml.inst
ucr set umc/saml/idp-server=https://${FQDN}/simplesamlphp/saml2/idp/metadata.php
univention-run-join-scripts --force --run-scripts 92univention-management-console-web-server.inst

In case UCS is directly exposed to the internet and must serve correct HTTPS certificates, the following UCR variables can be set:

ucr set saml/apache2/ssl/certificate=<cert.file> \
        saml/apache2/ssl/key=<key.file> \
        saml/apache2/ssl/ca=<ca.file>
# optional, if required
ucr set saml/apache2/ssl/certificatechain=<chain.file>
service apache2 restart

Other UCS servers

On all other UCS servers in the domain, the following must be executed for Single Sign On to work with UMC

ucr set ucs/server/sso/fqdn="${SSO_FQDN}" \
        umc/saml/idp-server=https://${SSO_FQDN}/simplesamlphp/saml2/idp/metadata.php
univention-run-join-scripts --force --run-scripts 92univention-management-console-web-server.inst

To have working Single Sign On work for new UCS servers in the domain, a UCR policy should be configured and assigned to servers before installation, which sets ucs/server/sso/fqdn to the correct FQDN.

4 Likes