Problem: Keycloak Installation Fails and System Services Become Unavailable

Knowledge Base Community
, , , ,
1

Problem: Keycloak Installation Fails and System Services Become Unavailable

Environment

  • Product: Univention Corporate Server (UCS)
  • Version: UCS 5.0-x
  • Component: Keycloak / SAML / Univention Management Console (UMC)

Problem Description

During the installation of the Keycloak app, the process gets stuck midway and the server becomes partially unresponsive. Remote access (e.g., SSH) may stop working, while only the local web interface remains accessible.

System diagnostics indicate that the join script 50keycloak.inst is pending. Attempting to execute the script manually results in the process halting at approximately 55%.

The join.log file shows errors similar to:

ERROR: Container did not come up healthy
/usr/lib/univention-install/50keycloak.inst: FATAL:
EXITCODE=2

As a result, most system services fail to start, and the Univention Management Console (UMC) becomes partially or completely unavailable.

Root Cause

The Keycloak container fails to start correctly during the installation or join process, preventing the join script 50keycloak.inst from completing. This failure blocks further join operations and disrupts UCS web services that depend on a functioning SSO configuration.

Solution

To quickly restore system access and revert to a working SAML configuration using SimpleSAMLphp, follow these steps.

:warning: Important: These steps remove the Keycloak app and revert the SSO configuration to the default SimpleSAMLphp provider. Proceed carefully if Keycloak was previously configured in production.

1. Remove the Keycloak App

Remove the incomplete or faulty Keycloak installation:

univention-app remove keycloak

This command stops and removes the Keycloak container, cleaning up the app configuration.

2. Reset the UMC SAML Configuration

Reconfigure the Univention Management Console to use SimpleSAMLphp as its SAML Identity Provider:

ucr set umc/saml/idp-server=https://ucs-sso.$(hostname -d)/simplesamlphp/saml2/idp/metadata.php

This restores the default SSO endpoint used by UCS systems prior to Keycloak integration.

3. Execute the UMC Web Server Join Script

Manually re-run the join script for the UMC web server to reinitialize SSO configuration and restore management access:

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

4. Restart UMC and Apache Services

Restart the necessary services to apply the changes:

systemctl restart univention-management-console-server.service
systemctl restart apache2.service

Verification

After completing the steps:

  1. Access the UMC via the browser at
    https://<ucs-hostname>/univention/management/

  2. Confirm that login using SimpleSAMLphp SSO works correctly.

  3. Check the system health via:

    univention-check-join-status

    Ensure that no join scripts remain pending.