Question:
How does the authentication flow work when a user logs into the UMC (Univention Management Console) with SAML/Keycloak?
Answer:
The SAML authentication process with Keycloak involves five main steps:
Step 1: User initiates login
A user opens https://schoolserver.school.de/univention/. The UMC detects that the user is not authenticated and redirects to Keycloak at https://auth.school.de/realms/ucs.
Step 2: Keycloak authenticates the user
The user enters their credentials in Keycloak. Once validated, Keycloak generates a SAML assertion containing:
- Issuer: https://auth.school.de/realms/ucs
- Subject: username
- Digital signature (cryptographically signed)
Keycloak then redirects back to the school server’s UMC with the SAML assertion in an HTTP POST request.
Step 3: UMC validates the SAML assertion
Upon receiving the SAML assertion, the UMC validates the digital signature to confirm that Keycloak is indeed the issuer. The UMC uses Keycloak’s certificate stored at /usr/share/univention-management-console/saml/idp/*.xml to verify the signature. If validation succeeds, the UMC extracts the username from the assertion and looks up the corresponding LDAP entry on the Primary.
Step 4: User accesses a module (e.g., Arbeitsgruppen)
When the user clicks on a module like “Arbeitsgruppen” (Workgroups), that module needs to retrieve LDAP data from the Primary. The module requests an authenticated LDAP connection, and the UMC provides one using the currently logged-in user’s credentials.
Step 5: LDAP server validates the authentication
When the module makes LDAP queries to the Primary, the LDAP server receives the request with the SAML assertion. The LDAP server must validate this assertion using the configuration in /etc/ldap/sasl2/slapd.conf.
The slapd.conf file tells the LDAP server:
- Where are the Keycloak certificates? (saml_idp0: …)
- Which clients are allowed to use SAML? (saml_trusted_sp0: …)
- How is the user identified in LDAP? (saml_userid: …)
Success case: If the Primary has umc/saml/idp-server properly configured, slapd.conf contains the necessary saml_idp0 entries. The LDAP server can validate the SAML assertion and return the requested data.
Error case: If the Primary does NOT have umc/saml/idp-server configured, slapd.conf lacks the saml_idp0 entries. The LDAP server cannot validate the SAML assertion, resulting in the error: “SAML assertion issuer https://auth.school.de/realms/ucs is unknown”. The module will hang indefinitely waiting for successful authentication.
Solution:
On the Primary domain controller, ensure that umc/saml/idp-server is set:
ucr set umc/saml/idp-server='https://auth.school.de/realms/ucs/protocol/saml/descriptor'
This UCR variable triggers the generation of the correct /etc/ldap/sasl2/slapd.conf with the required SAML IDP and trusted service provider entries. After setting this variable, restart the LDAP service:
systemctl restart slapd
If the issue persists, you can manually regenerate the configuration by running:
univention-run-join-scripts --force --run-scripts 92univention-management-console-web-server.inst