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.
Note: If you plan to use an own certificate from a public CA and want to skip the use of univention-certificate in the following scenario 1 or 2, then be aware that the certificates must be in the standard certificates directory (/etc/univention/ssl/FQDN/) and certificates name (cert.pem, private.key, CAcert.pem) to let the internal scripts run.
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 all servers that are running the Single Sign On via simplesamlphp (i.e.: the Primary and all Backup directory nodes), 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=</etc/univention/ssl/FQDN/cert.pem> \
saml/apache2/ssl/key=</etc/univention/ssl/FQDN/private.key> \
saml/apache2/ssl/ca=</etc/univention/ssl/FQDN/CAcert.pem>
# optional, if required
ucr set saml/apache2/ssl/certificatechain=</etc/univention/ssl/FQDN/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
univention-certificate new -name "${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/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=</etc/univention/ssl/FQDN/cert.pem> \
saml/apache2/ssl/key=</etc/univention/ssl/FQDN/private.key> \
saml/apache2/ssl/ca=</etc/univention/ssl/FQDN/CAcert.pem>
# optional, if required
ucr set saml/apache2/ssl/certificatechain=</etc/univention/ssl/FQDN/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="${FQDN}" \
umc/saml/idp-server=https://${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.
Changing the server that is used for password changes
During the Single Sing On the password expiry is checked and if expired the user has to change the password. By default the password change request goes to the internal name of the UCS system. In some setups this may not work, for example if the system is available under an external name that is different to the internal UCS name. The server that is used for password changes can be configured with the UCR variable ucs/server/sso/password/change/server (which defines the FQDN of the UCS instance used to change user passwords). This UCR variable is available in UCS 5.0-4.
ucr set ucs/server/sso/password/change/server=$FQDN
service apache2 restart