Single-Sign-On into Keycloak using Admidio as a SAML 2.0 Identity Provider

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. These instructions will guide you through the process of connecting Keycloak to Admidio to use Admidio's login. For general instructions, and other apps, please visit the general Single-Sign-On overview page.

Keycloak supports both SAML 2.0 and OpenID out of the box, so no additional extensions or plugins are needed.

Throughout the document we will assume you have both Admidio and Keycloak already set up properly at https://admidio.local/ and https://keycloak.local/. Please modify these URLs to your actual installation.

As a first step, one needs to configure Admidio to act as a SAML 2.0 Identity Provider (IdP). This has to be done once and is not specific to any client. Please follow this guide: #a_basic_setup_for_admidio_as_a_saml_id_provider

Basically, one (1) needs to create a cryptographic key to sign message and choose a unique EntityID. The page preferences https://admidio.local/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

Setting up a client (SAML “Service Provider” - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Keycloak in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

• Configure the Service Provider (SP) – Keycloak in our case – with Admidio's link to the metadata file, which will tell Keycloak the URLs for the SSO, logout endpoints, and which key is used for signatures.
• In Admidio, create a new SAML client. Keycloak provides a metadata URL to configure the IdP. Paste that URL into Admidio it and let it automatically load the configuration from Keycloak.
  • Choose an easily understood label for the client (only used in Admidio's list of clients, but has no technical use)
• In Admidio, also choose whether sent messages should be signed or encrypted. The crypto key generated in the general SAML setup will be used.
• Optionally select which profile fields should be mapped to SAML attributes and sent to the client, and configure which group memberships should be transmitted.
  • In Keycloak, set up mappers to import SAML attributes from Admidio to Keycloak fields, and mappers to assign users to groups or roles, based on Admidio roles.

Keycloak provides SAML 2.0 and OpenID Connect support out of the box. It even supports multiple SAML and OpenID Connect Identity Providers (IdP).

To add Admidio as an Identity Provider to log into Keycloak, go to your desired realm, choose “Identity Providers” on the left and add a new “SAML v2.0” Provider.

Keycloak supports auto-configuration, so copy the SAML Metadata URL from Admidio's preferences and paste it into the “SAML entity descriptor” field. Keycloak will load the SAML IdP configuration from Admidio and populate all fields.

After clicking “Add”, the SAML Provider is saved in Keycloak and can be further configured.

It is now a good idea to open Admidio in a second browser window and configure Keycloak and Admidio in parallel.

Now, return to Admidio's SSO preferences page, go to the “Single-Sign-On Client Administration” (the button right above the “Save” button), and create a new client.

Copy the Metadata Url from Keycloak, paste it into the corresponding input field at the top and click “Load Client Metadata”. This should load all settings from Keycloak and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name, but the name will be displayed in the login form.

It is also a good idea to require requests to be signed, and to sign all messages. Choose whichever level of security (request signing without requiring, require signing, or even encrypting all messages) fits you. You only need to ensure that the settings in Admidio and Keycloak are be consistent.

Keycloak also provides some more configuration settings that allow fine-tuning the SAML login behavior. The defaults should work fine, but changes can be made if other settings are prefered.

Admidio can be configured to send any profile field as a SAML attribute in the login response.

However, as there is no specification of the meaning of particular SAML attributes, Keycloak by default does map those fields to its user's profile data. One can, however, set up attribute mappers in Keycloak to use certain SAML attributes and assign them to the user's profile. Go to the “Mappers” tab of the SAML provider in Keycloak and add new mappers of type “Attribute Importer”. It is a good idea to choose “Force”, which will always use the attribute value from Admidio and update the keycloak user on every login. The “Attribute Name” is the SAML attribute, while the “User Attribute Name” is Keycloak's profile field name.

Keycloak uses the term “Role” to refer to a particular permission (e.g. view users, manage users, delete account, etc.) and uses “Group” to refer to a set of roles that can be assigned to a user in bulk.

Keycloak's Mapper feature allows Admidio groups to both assign individual roles to a user, or assign the user to a particular group (which gives all permissions defined for that group). For this to work, clearly, Admidio must be configured to include the Admidio roles of a user as SAML attribute (typically called “roles” or “groups”, but any other name will work, too, as long as the new name is properly used in Keycloaks mapper). Use either the “Advanced Attribute to Group” or the “Advanced Attribute to Role” Mapper type.

Admidio and Keycloak should now be set up to use Admidio for logging in to Keycloak. If you log out of Keycloak (or open Keycloak in an incognito browser window) and go to the keycloak admin location, you should see the login screen with the choice of logging in with password or via SAML.

After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Keycloak.

If the account already exists (e.g. because you are in a hybrid setup with multiple identity providers, e.g. SAML and OpenID through Admidio), then Keycloak will ask for permission to add the SAML login to the existing account. The user must additionally log in to the existing account to prevent security issues:

Your user should now be logged in and have the proper permissions/roles