HTTPS is supported for the profiles test-local-3nodes, test-network and prod-network.

Certificate

The certificates are held in the configuration profile folder (e.g, ${MEDCO_SETUP_DIR}/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

Enable HTTPS for the Local Local Deployment

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.

Configure HTTPS for the Network Test and Production Deployments

For these profiles, HTTPS is mandatory. The profile generation scripts generate 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 one of the Glowing Bear instance.

There is currently only one way 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.

This set of pages provide configuration instructions for MedCo. Note that all of them are not necessarily always needed, follow one of the deployment instructions to know which ones are.

Prerequisites

• 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.

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.

• 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.

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.

  • Mapper Type: Username Template Importer.

  • Template: ${ATTRIBUTE.swissEduPersonUniqueID}

• Save the changes.

Setup a certificate

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.

Register Keycloak instance as a Service Provider in SwitchAAI

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.

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).

• Home URL: the address of the MedCo node, at which the UI Glowing Bear can be accessed. Example: https://medco-demo.epfl.ch/.

2. Descriptive Information

3. Contacts

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.

Passwords Configuration

In each compose profile you will find a .env file containing configuration options. Among them are the passwords to be set. Note that most of those passwords configured that way will only work on a fresh database. Example:

PostgreSQL administration user

POSTGRES_PASSWORD configures the password for the postgres administration user of the PostgreSQL database.

PgAdmin user

PGADMIN_PASSWORD configures the password for the admin user of the PgAdmin web interface. Note that it is necessary to set it only if your deployment profile deploys this tool.

Keycloak administration user

KEYCLOAK_PASSWORD configures the password for the keycloak administration user of the default master realm of Keycloak.

I2b2 Wildfly administration user

I2B2_WILDFLY_PASSWORD configures the password for the admin user of the wildfly instance hosting i2b2.

I2b2 service user

I2B2_SERVICE_PASSWORD configures the password for the AGG_SERVICE_ACCOUNT user of i2b2, used to operate background automated tasks by the i2b2 services.

I2b2 default user

I2B2_USER_PASSWORD configures the password for the default i2b2 and demo users used by MedCo.

Here follows some MedCo-specific instructions for the administration of Keycloak. For anything else, please refer to the Keycloak Server Administration Guide. Those instructions do not necessarily need to be all followed for all deployments, refer to the deployment guide to know which ones are important.

Accessing the web administration interface

You can access the Keycloak administration interface at http(s)://<node domain name>/auth/admin. For example if MedCo is deployed on your local host, you can access it at http://localhost/auth/admin. Use the admin default credentials if you had just deployed MedCo.

User Management

Default users

The default configuration shipped with the MedCo deployments come with two users.

Admin user

The default admin credentials has all the admin access to Keycloak, but no access rights to MedCo. Its credentials are :

• User keycloak

• Password keycloak (unless configured otherwise through the .env file)

Test user

The default MedCo user has all the authorizations to run all types of MedCo query. It is this user you should use to log in MedCo. Its credentials are:

• User test

• Password test

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.

MedCo Default Settings

medco OpenID Connect client

The default Keycloak configuration provides an example of a fully working configuration for deployments on your local host. In other cases, you will need to modify this configuration.

Access the configuration panel of the MedCo client by going to the Clients tab, and click on the medco client. Then, in the Settings tab, fill Valid Redirect URIs to reflect the following table (you can delete the existing entries):

In the same tab, fill Web Origins with + and save.

Securing a production deployment

Changing default passwords

Both keycloak and test users comes with default passwords. For a production deployment they need to be changed:

• Go to the configuration panel Users, click on View all users.

• For each of the users you want to change the password of:

  • Click on Edit, then go the Credentials tab.

  • Enter the new password of the user

  • Optionally toggle to OFF the Temporary button; if ON the user at the next login will need to update his password.

  • Click on Reset Password.

Changing default realm keys

The example configuration comes with default keys. They have to be changed for a network deployment where there are several Keycloak instances.

• Go to the configuration panel Realm Settings, then to the Keys tab and Providers subtab.

• Click on Add keystore... and add the three following providers:

  • aes-generated

    • Console Display Name: aes-medco

    • Priority: 100

  • hmac-generated

    • Console Display Name: hmac-medco

    • Priority: 100

• • rsa-generated

    • Console Display Name: rsa-medco

    • Priority: 100

• Finally, delete all the other key providers listed that you did not just add. They should be named xxx-generated. Note that it is normal if you get logged out during the operation, just log back in and continue the process.

Enabling brute force detection

• Go to the configuration panel Realm Settings, then to the Security Defenses tab and Brute Force Detection subtab.

• Toggle to ON the Enabled button.

• Fill the following:

  • Max Login Failures: 3

  • Wait Increment: 30 Seconds

  • Save the configuration.