How-to: Migrate from SimpleSAMLphp to Keycloak

Knowledge Base Community
, , , , ,
#1

How to:

Migrate from simpleSAMLphp to Keycloak

Starting with UCS 5.2 the Keycloak app replaces the apps SimpleSAMLphp and OpenID Connect Provider as the default identity providers in UCS. The reason for this change is that Keycloak has many advantages in terms of features, configurability, and maintainability over the alternatives, for example, Keycloak provides OIDC and SAML endpoints in one component.

This article describes the migration of the single sign-on authentication from simpleSAMLphp to Keycloak for the UCS Portal.

Install Keycloak

Hint

Keycloak automatically creates SAML SPs (clients in Keycloak) for every UCS Portal server that is reachable / turned on

If server in the domain are switched off, they can be added in Keycloak manually as described here
or automatically via the Keycloak join script 50keycloak.inst

Install Keycloak via the AppCenter

Install Keycloak via the AppCenter. During the installation process you will have to tell ucs on which host keycloak should be installed.
You will then be asked for configuration information in the UMC. Unless configured otherwise, the input fields can be left as they are.

install_keycloak

install_keycloak_which_host

install_keycloak_start_installation

Installation via Shell

Step 1: Install Keycloak via univention-app

In the shell use the command:

univention-app install keycloak

to install Keycloak on the system you´re currently on.

Check if all UCS Portal servers were added as SPs in Keycloak

Check via UMC

Step 1: Go to the Keycloak Administration UI

On the Portal Site of the server, where Keycloak is installed, click on the Keycloak tile and log in with an administrative user.

Step 2: Change to ucs Realm

In Keycloak change the realm you´re currently on to ucs

change_realm

Step 3: Go to Clients

Click on “Clients” on the left sidebar. You will then see a list of all Clients added to Keycloak as SP. Check, if all your Clients were added.

client_list_keycloak

Check via Shell

Use the univention-keycloak command

Use the command:

univention-keycloak saml/sp get --json

to get a list of all SPs that were added to Keycloak. Check, if all your UCS Portal Servers were added.

Add missing SPs

You can skip this step if all of your Portal servers were added correctly as SPs in Keycloak.

Automatically

To add missing SPs, the servers have to be reachable and turned on, so you can run the join script 50keycloak.inst on the system, where Keycloak is installed:

univention-run-join-scripts --run-scripts 50keycloak.inst --force

Manually

Add the missing servers manually, as described here.

Set UCR Variables

All steps are also performable in the UMC, described here.
To use Keycloak as the default authentication on your Portal servers set the following UCRV:

ucr set umc/saml/idp-server="https://ucs-sso-ng.$(hostname -d)/realms/ucs/protocol/saml/descriptor"

udm portals/entry modify --dn "cn=login-saml,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" --set activated=TRUE

ucr set portal/auth-mode='saml'

Annotation: If you still want to be able to log in to the UMC of a specific node as an administrator (by entering the IP address of the corresponding node) via the ≡ menu / Login, better keep the default value (‘ucs’).

After successfully setting all needed UCR Variables restart slapd and univention-portal-server:

systemctl restart slapd univention-portal-server

Fix redirect issues on nodes

If you have some failures with the redirect for the sso login, you could try this to fix the issue.

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

systemctl restart apache2.service

3 Likes
Error in keycloak during join
#2
#3
#4
Mastodon