Configuring SwitchAAI Authentication
This guide walks you through the process of configuring Keycloak as a Service Provider to one or more SwitchAAI identity provider(s), in order for MedCo to rely on SwitchAAI for user authentication.
A MedCo network is up and running, with one or more functional Keycloak within the network.
One or several identity provider(s) part of the SwitchAAI federation is/are chosen to be used as user source.
The institution at which the Keycloak of MedCo is deployed is ready to accept being registered as the home organization.
Note that right now the SwitchAAI WAYF (Where Are You From) mechanism is not supported (i.e. the web UI used to select with institution the user wishes to login). This means that you will need to register in Keycloak each identity provider you wish to support.
Note also that the process described in this guide will need to be repeated for each instance of Keycloak deployed, if there are more than one in the MedCo network.
Configure the identity provider(s) in Keycloak
The following instructions are to be executed on the administration UI of Keycloak, e.g. https://medco-demo.epfl.ch/auth/admin.
Configure the first login flow
The behavior of Keycloak during the very login of users through the identity provider is highly customisable. We propose below an example of a working flow but this can be changed to fit your need.
Navigate to Authentication > Flows, select First Broker Login and make a Copy of it. Name it for example SwitchAAI-Test Demo IdP First Broker Login.
Change the list of executions to make it look like the following image.
Add the identity provider
In the Identity Providers menu, choose Add provider... > SAML v2.0
Specify an Alias. Note this will not be changeable later without redoing the whole process. Example: SwitchAAI-Test.
Add the username mapper
We need to import a unique but intelligible username in Keycloak from the identity provider. For this we use the SwitchAAI mandatory attribute swissEduPersonUniqueID.
Open the Mappers tab and click Create.
Fill the field as:
Name: SwitchAAI Unique ID.
Setup a certificate
A certificate compliant with the SwitchAAI federation needs to be generated and configured. First to generate a self-signed certificate that meets their requirements. You will need from the Keycloak instance:
Its FQDN (fully-qualified domain name). Example: medco-demo.epfl.ch.
Its SAML entityID, that you can find out in the XML descriptor from the Export tab of the previously configured Keycloak identity provider. Example: https://medco-demo.epfl.ch/auth/realms/master.
Once you have generated the certificate, set it up in Keycloak:
Navigate to the settings page Realm Settings > Keys > Providers and select Add Keystore... > rsa.
Specify a name in Console Display Name. Example: rsa-switchaaitest.
Register Keycloak instance as a Service Provider in SwitchAAI
The following instructions are to be executed in the . As a result, a Keycloak instance will be registered as a service provider linked to a home organization in the SwitchAAI federation.
Register new resource
Click Add a Resource Description and fill the 7 categories of information according to the following instructions. Note that if some fields are not listed in this documentation, their value are not important for the registration of the Keycloak instance and can be set according to the explanations provided by the resource registry.
1. Basic Resource Information
Entity ID: the same SAML entityID you used to generate the certificate. Example: https://medco-demo.epfl.ch/auth/realms/master.
Home Organization: the organization that hosts the Keycloak instance currently being registered. The responsible persons of the organization specified here will need to approve the registration. This will typically be the the institution where the MedCo node is deployed. For the purpose of our test we are using AAI Demo Home Organization (aai-demo-idp.switch.ch, AAI Test).
2. Descriptive Information
4. Service Locations
SAML2 HTTP POST binding (x2): the URL at witch the SwitchAAI infrastructure will communicate with the Keycloak instance. You will find it in the configuration page of the configured identity provider in Keycloak under Redirect URI. Example: https://medco-demo.epfl.ch/auth/realms/master/broker/SwitchAAI-Test/endpoint
5. Certificates
Copy/paste in this field the PEM part of the certificate that was previously generated. Note that in the example showed below the certificate has already been validated through a separate channel.
6. Requested Attributes
Put on Required at least the following attributes. Note that the release of attributes needs to have a justification.
E-mail (email). Example reason: Identify user for being able to assign them specific authorizations.
Unique ID (swissEduPersonUniqueID). Example reason: Get a unique ID of user.
7. Intended Audience and Interfederation
Get the new resource approved
Once submitted, the responsible persons from the home organization will need to approve the new resource and validate the fingerprint of the certificate submitted. This is a manual process that will most likely be done through email.
Once this is done, the setup should be functional, and the users will be able to select the configured identity provider to login. Don't forget that this covers only users' authentication, their authorization needs to be handled manually through Keycloak after they login at least once.
