Welcome to our fourth dive into the world of Univention apps! In this blog series, we regularly highlight exciting applications from our App Center. Today, we’re checking out Keycloak, an identity provider (IdP) that helps UCS admins manage user authentication and authorization in a secure and centralized way.
Table of Contents
Functionality of the Keycloak-App
Keycloak is an Open Source identity and access management (IAM) tool. It offers handy features like Single Sign-On (SSO), identity brokering, social login, and role-based access control (RBAC). If you need a central and secure way to handle user access in your organization, Keycloak’s flexibility and robust features have got you covered. For UCS admins, Keycloak can seriously boost the efficiency and security of the IT infrastructure.
How does Keycloak work?
Key features of Keycloak
The Keycloak app uses a Docker image with additional files that support data synchronization between instances within the same domain. Keycloak relies on the UCS directory service as the backend for user accounts, verifying user credentials by delegating authentication to the UCS LDAP directory service and storing some user attributes. Keycloak uses a SQL database to store its own configuration data.
A core feature of Keycloak is its support for SAML and OpenID Connect (OIDC):
- SAML Identity Provider (SAML IdP): This is Keycloak’s SAML interface that offers user authentication as a service via SAML. Keycloak can act as a SAML IdP by receiving and authenticating user requests.
- SAML Service Provider (SAML SP): This SAML interface in Keycloak delegates user authentication to an external Identity Provider (IdP). Essentially, Keycloak passes the authentication task to another SAML IdP.
Similarly, OpenID Connect integration works as follows:
- OIDC Provider (OIDC IdP): Keycloak’s OIDC interface offers user authentication as a service. Keycloak acts as an OpenID Connect Provider and authenticates users.
- OIDC Relying Party (OIDC RP): This OIDC interface in Keycloak delegates user authentication to an external OpenID Connect Provider. Here, Keycloak acts as a client that passes the authentication task to another OpenID Connect Provider.
All instances that can request Keycloak to authenticate a user are called Keycloak clients. This includes all OIDC Relying Parties and SAML Service Providers.
How to Install Keycloak on UCS
After clicking Install in the Univention App Center, select the appropriate machine in your UCS environment from the drop-down menu and click Continue. You can only install Keycloak on UCS systems that have the system role of either Primary Directory Node or Backup Directory Node.
Installation of the Keycloak-App
In the next dialog, you’ll set up a few basic options. Decide whether Keycloak should start automatically (Autostart drop-down menu). You’ll also need to enter the Fully Qualified Domain Name (FQDN) of the UCS IdP and the dedicated path where Keycloak will be available. At the bottom of the dialog, there are pre-selected options for Apache host configuration and the DNS entry for the Keycloak FQDN in the UCS domain. You can also change the log level and database settings here. Usually, you can go with the default settings and start the installation with a click.
During the installation, a PostgreSQL database is automatically set up to store Keycloak’s configuration data. Keycloak uses this database for all additional installations of the app within the UCS domain. Since this default database doesn’t provide replication or failover capabilities, administrators can choose to use a different database and enter this in the app settings (see the section “Keycloak: Failsafe and High Availability”).
The first installation of the Keycloak app in the UCS domain creates an administrative user named admin, with the password stored in the file /etc/keycloak.secret. This account is used to perform the initial configuration of Keycloak.
After the installation is complete, the UCS portal will display a new tile named Keycloak for administrators. Clicking on it opens the Keycloak Admin Console in your web browser. Unless specified otherwise during installation, you can access it at the URL https://ucs-sso-ng.$domainname/admin/, where $domainname represents your UCS domain name.
By default, all users in the Domain Admins group can log into the Keycloak Admin Console.
Register Domain Admins with Keycloak
How to Change Keycloak Settings After Installation
You can change many Keycloak settings via UCR variables (System / Univention Configuration Registry). Specific settings can be adjusted through the app settings. To access the app settings, go to the App Center, select Keycloak from the installed apps, click on Manage installation on the right, choose the server, and open the app settings from the drop-down menu under More. After clicking Apply changes, the App Center will reinitialize the Docker container for the Keycloak app. This means the current Keycloak container will be removed, and a new container with the updated settings will be started on the UCS server.
Manage Keycloak installation
The UCS developers have ensured that in current versions of Keycloak, admins can freely choose the name of the Keycloak endpoint. This allows for making Single Sign-On available over the internet. Additionally, the integration with the Self-Service app has been improved. The article New Features for Keycloak as Upcoming Standard Identity Provider of UCS provides detailed information on these new features. You can find all configuration options, tips, and tricks for operation in the Settings section of the Keycloak manual.
Keycloak: Failsafe and High Availability
You can install Keycloak multiple times within a UCS domain. All installations share the same configuration, are accessible under the same name on the network, and share login sessions. This distributes the load across multiple machines and provides a degree of failover.
Since Keycloak uses a central database to store user data, admins should consider running the database system as a cluster to ensure Keycloak is truly failsafe and highly available. Keycloak doesn’t come with a built-in cluster for the database by default; however, you can set up an external database in the app settings. Running a cluster with the database servers included in Univention Corporate Server is possible, but it’s not entirely straightforward.
Migrating from SAML/OpenID Connect to Keycloak
Keycloak is set to replace SimpleSAMLphp and Kopano Konnect. By the time UCS 5.2 is released, Keycloak will be the only IdP option. For details on this change, check out the blog post SimpleSAMLphp and Kopano Konnect Deprecated – Keycloak Will Be the Only IDP in UCS 5.2.
If you’re using SimpleSAMLphp with Univention Corporate Server, you should plan to switch to Keycloak in the coming months. For those setting up a new UCS environment and looking to implement Single Sign-On, best start with Keycloak right away.
The UCS developers provide an English guide for migrating from SimpleSAMLphp (SAML) and OpenID Connect Provider to the Keycloak app. This guide is perfect for admins wanting to move to Keycloak before UCS 5.2 is out. Also, current UCS versions contain the Python script univention-keycloak-migration-status, which backs up and removes all IdP client object settings on the Primary Directory Nodes.
Making the Most of Keycloak
Keycloak is a powerful Open Source solution for identity and access management that helps UCS administrators securely and centrally manage user authentication and authorization.
Have you already tried the Keycloak app and migrated an existing Single Sign-On solution? Or did you set up Univention Corporate Server from scratch and start with Keycloak right away? Share your experiences and tips with us and the community—we’d love to hear your stories and insights!
Comment on this post and visit the Forum Univention Help!
Image source: Icon created by Freepic from flaticon.com
