HTTPS is supported for the profiles test-local-3nodes and test-network.
The certificates are held in the configuration profile folder (e.g, ~/medco-deployment/configuration-profiles/test-local-3nodes):
certificate.key: private key
certificate.crt: certificate of own node
srv0-certificate.crt, srv1-certificate.crt, …: certificates of all nodes of the network
To enable HTTPS for the profile test-local-3nodes, replace the files certificate.key and certificate.crt from the configuration profile folder with your own versions. Such a certificate can be obtained for example through Let’s Encrypt.
Then edit the file .env from the compose profile, replace the http with https, and restart the deployment.
For this profile, HTTPS is mandatory. The profile generation scripts generates and use default self-signed certificates for each node. Those are perfectly fine to be used, but because they are self-signed, an HTTPS warning will be displayed to users in their browser when accessing Glowing Bear. There are two ways of avoiding this warning:
Configuring the browsers of your users to trust this certificate. This procedure is specific to the browsers and operating systems used at your site.
Use a certificate obtained by an authority trusted by the browser you are using: see below.
If you wish to use a certificate from your own making, gather its key and the certificate itself. Note that using your own certificate is only needed on the central node (as it is the one hosting the web application Glowing Bear). In the configuration profile of the central node (~/medco-deployment/configuration-profiles/test-network-<network name>-node<node index>/) copy the certificate and its key in the respective files certificate.crt and certificate.key. Then duplicate the file certificate.crt in srv0-certificate.crt. Restart the deployment and the central node configuration is ready.
Now the other nodes need to get this certificate to trust it. Get and copy the srv0-certificate.crt file into each of the configuration profile directory of the other nodes, and restart all the deployments. The configuration of HTTPS is now ready.
Here follows some MedCo-specific instructions for the administration of Keycloak. For anything else, please refer to the Keycloak Server Administration Guide.
In the case of the development profile dev-local-3nodes (i.e. without reverse proxy), the address is http://localhost:8081/auth/admin. In the other cases (with the reverse proxy), the address is http://<node domain name>/auth/admin. The credentials are :
User keycloak
Password keycloak by default, or whatever else was configured at the initial deployment.
When deploying the test-local-3nodes profile without HTTPS on a machine other than localhost, the administration interface will refuse to load. To solve this, access pgAdmin (see The PostgreSQL database) and execute the following SQL on the keycloak database:
You need to restart the Keycloak docker container to enable the changes.
Import the provided realm configuration into Keycloak. This will create the MedCo client with the appropriate roles.
Go to the Import menu
Click on Select file and select the file keycloak-medco-realm.json that you will find in ~/medco-deployment/resources/configuration.
Select to import everything, and to Skip if resources already exist
In the Settings tab, fill Valid Redirect URIs according to the following table:
In the same tab, fill Web Origins with + and save.
Add a user
Go to the configuration panel Users, click on Add user.
Fill the Username field, toggle to ON the Email Verified button and click Save.
In the next window, click on Credentials, enter twice the user’s password, toggle to OFF the Temporary button if desired and click Reset Password.
Give query permissions to a user
Go to the configuration panel Users, search for the user you want to give authorization to and click on Edit.
Go to the Role Mappings tab, and select medco (or another client ID set up for the MedCo OIDC client) in the Client Roles.
Add the roles you wish to give the user, each of the roles maps to a query type.
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.
You have access to the SwitchAAI Resource Registry.
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.
The following instructions are to be executed on the administration UI of Keycloak, e.g. https://medco-demo.epfl.ch/auth/admin.
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.
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.
Specify a Display Name, which will be displayed to the user in the login page. Example: SwitchAAI-Test Demo IdP.
Specify the Single Sign-On Service URL of the identity provider you are linking with. Example: https://aai-demo-idp.switch.ch/idp/profile/SAML2/POST/SSO.
Specify the First Login Flow previously configured to use. Example: SwitchAAI-Test Demo IdP First Broker Login.
Toggle to ON the following buttons:
Enabled
Trust Email
HTTP-POST Binding Response
HTTP-POST Binding for AuthnRequest
Validate Signature
Specify the NameID Policy Format as Persistent.
Add the certificate(s) (PEM format, separated by commas if there are several of them) of the identity provider you are linking with in Validating X509 Certificates.
Save the changes.
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.
Mapper Type: Username Template Importer.
Template: ${ATTRIBUTE.swissEduPersonUniqueID}
Save the changes.
A certificate compliant with the SwitchAAI federation needs to be generated and configured. First follow this SwitchAAI guide 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.
Specify a Priority higher than any other RSA key. Example: 150.
In Private RSA Key and X509 Certificate fields, copy/paste the respective PEM parts of both the private key and the certificate that were previously generated.
The following instructions are to be executed in the AAI Resource Registry. As a result, a Keycloak instance will be registered as a service provider linked to a home organization in the SwitchAAI federation.
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.
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).
Home URL: the address of the MedCo node, at which the UI Glowing Bear can be accessed. Example: https://medco-demo.epfl.ch/.
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
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.
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.
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.
Deployment Profile
Valid Redirect URIs
test-local-3nodes
http(s)://<node domain name>/glowing-bear
test-network
https://<node domain name>/glowing-bear
dev-local-3nodes
http://localhost:4200
PgAdmin can be accessed through http://<node domain name>/pgadmin with username admin and password admin (by default). To access the test database just create a server with the name MedCo, the address postgresql, username postgres and password postgres (by default).
