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.
Step 1: 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 script50keycloak.inst
Installation via UMC
Step 1: 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.
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.
Step 2: 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
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.
Check via Shell
Step 1: 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.
Step 3: 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.
Step 4: 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'
After successfully setting all needed UCR Variables restart slapd and univention-portal-server:
systemctl restart slapd univention-portal-server