With UCS 5.2 Keycloak will become the standard IDP for SAML and OpenID Connect authentication and will replace the current SimpleSAMLPHP and Kopano Connect apps. Read more about the big picture in our blog article Migration of the Identity Provider in UCS – Keycloak App now Part of the Support Scope. The first step we made was the release of Keycloak as a supported Univention app at the end of 2022. Since then, a lot of work has been done to make the Keycloak app a worthy replacement for the SimpleSAMLphp integration.
So, we are making steady progress on our mission to reach feature parity with our SimpleSAMLphp integration. And since the initial release of the Keycloak app, we have also released several app updates each adding new features in terms of a smooth integration into UCS and more configurability.
In this article, we would like to showcase some of the work that has been done over the last few months.
Single Sign-on through External Public Domain Name and Let’s Encrypt Integration
By default, the UCS Keycloak app uses an internal name for the Single Sign-on endpoint. For administrators who want Single Sign-on availability from the internet, we have added app settings and documentation that allow them to freely choose the name of the Keycloak endpoint.
A common scenario is to have the Keycloak server running on a different name than the UCS portal:
- portal.extern.com -> UCS Portal
- auth.extern.com -> Keycloak Single Sign-on endpoint
There are some preconditions for this setup. You must have a public DNS record for the name of the Keycloak server and you need a valid certificate for this server name, but once that is available you can configure this setup with the following app settings on the command line or with the UMC app settings for the Keycloak app.
- keycloak/server/sso/fqdn → auth.extern.com
- keycloak/server/sso/autoregistration → false
- keycloak/apache2/ssl/certificate → /path/to/certfificate/for/auth.extern.com
- keycloak/apache2/ssl/key → /path/to/private/key/for/auth.extern.com
- keycloak/csp/frame-ancestors → https://*.extern.com
Further information on how to configure such a setup can be found in the Keycloak documentation.
Another possible scenario would be to have the Keycloak server running with the same name as the UCS portal but in a different URL:
- portal.extern.com -> UCS Portal
- portal.extern.com/auth-> Keycloak Single Sign-on endpoint
We assume that the public DNS for the name of the UCS portal already exists and that a valid certificate is used. Again, the configuration can be done with the app settings in the Keycloak app:
- keycloak/server/sso/fqdn → portal.extern.com
- keycloak/server/sso/path → auth
- keycloak/server/sso/virtualhost → false
- keycloak/server/sso/autoregistration → false
See our documentation for a detailed description.
In both cases the integration of Let’s Encrypt certificates for the public domain name is just a matter of setting some UCR variables.
For the first scenario with the Keycloak server running on a different name than the UCS Portal/UMC, the Let’s Encrypt app configuration would be:
- Domain(s) to obtain a certificate for, separated by space: portal.extern.com auth.extern.com
- Use certificate in Apache: yes
These settings create a certificate for both names and uses this certificate in the web server configuration. And for the Keycloak app, the certificates can be configured with:
- ucr set keycloak/apache2/ssl/certificate=”/etc/univention/letsencrypt/signed_chain.crt”
- ucr set keycloak/apache2/ssl/key=”/etc/univention/letsencrypt/domain.key”
For the scenario with Keycloak and the UCS Portal/UMC running with the same name, the Let’s Encrypt app only needs to acquire the certificate for this one name:
- Domain(s) to obtain a certificate for, separated by space: portal.extern.com
- Use certificate in Apache: yes
And for Keycloak, we just have to make sure
- ucr set keycloak/server/sso/virtualhost=false
is set to indicate we want to use the global webserver configuration for Keycloak, including the certificate settings.
Password Change During Login and Onboarding After Self-Service Registration
In UCS, user passwords can expire. If a password expired, the user can not log in anymore and needs to change the password. This is often also used during onboarding workflows, where users get an initial password but are forced to change the password during the first login. Administrators can use the Univention Directory Manager option “User has to change password on next login” for such an onboarding, which internally is handled as an expired password.
We have added custom Keycloak extensions that check the password expiry of a user during login and allow them to change their password directly during the Keycloak login progress.
Likewise, the integration with the self-service registration for new users has been improved. With the self-service registration, users can create their accounts in the UCS IDM. To complete the process users have to verify the new account (typically using a token sent by e-mail). In one of the latest releases of the Keycloak app, we added an app setting to disable the login for user accounts that are not yet verified. Instead, the user is redirected to the self-service where the account verification is completed.
Guide for Migration from SimpleSAMLphp/Kopano Connect to Keycloak
The just published migration guide makes the migration from SimpleSAMLphp/Kopano-connect to Keycloak as easy and seamless as possible. It contains a general step-by-step guide as well as some specific examples of how apps can be migrated. With it, we have released an update to UCS that enables customers to use SimpleSAMLphp as a serviceprovider in Keycloak. This makes it possible to use Single Sign-on between services that were migrated to Keycloak, and those that still use SimpleSAMLphp while the migration is still in progress.
Single Sign-on with Kerberos
In work is the feature to authenticate to Keycloak with Kerberos tickets. If you have a UCS domain with client workstations that acquire Kerberos tickets during the user login process, it will be possible to authenticate with this Kerberos ticket to services that use Keycloak as IDP (provided that the browser is configured to allow Kerberos authentication) to enable a password-less login.
With the migration guide and with the Kerberos SSO, the Keycloak integration in UCS will have all functionality UCS users know from SimpleSAMLphp – with way more flexibility and features on its own. I hope this article gave a good overview, but if there are any open questions feel free to comment here on the blog or post on help.univention.com.
