Those authorizations allow the user to interact with API endpoints of the MedCo connector.
The minimum set of authorizations needed for users to use MedCo is the following:
medco-network
medco-network
This covers the calls related to the network metadata: list of nodes, keys, URLs, etc.
medco-explore
This covers the calls related to the building and requesting of explore queries and cohort saving. Note that an additional authorization among the is needed to be able to make explore queries.
medco-genomic-annotations
This covers the genomic annotations auto-completion and the querying of genomic variants.
medco-survival-analysis
This covers the calls needed for requesting computations of survival curves.
Explore Query Authorizations
Those authorizations set the types of result users will be able to get when making an explore query.
Those authorizations are ordered according to their precedence. This means that if a user has several of them, the authorization with the highest level will be selected.
patient_list: exact counts and list of patient identifiers from all sites
count_per_site: exact counts from all sites
count_per_site_obfuscated
medco-explore
medco-genomic-annotations
: obfuscated counts from all sites
count_per_site_shuffled: exact counts from all sites, but without knowing which count came from which site
count_per_site_shuffled_obfuscated: obfuscated counts from all sites, but without knowing which count came from which site
count_global: exact aggregated global count
count_global_obfuscated: obfuscated (at the site level) aggregated global count
It is important to choose strong unique passwords before a deployment, even more so if it contains real data or if it is exposed to the internet.
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.
As of v1.0.0, the provisioning of the configuration of Keycloak has changed and this setting is not effective. After the initial deployment, you must login to the administration interface with the default password (keycloak) and change it.
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.
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.
Prerequisites
A MedCo network is up and running, with one or more functional Keycloak within the network.
Keycloak
Here follows some MedCo-specific instructions for the administration of Keycloak. For anything else, please refer to the . Those instructions do not necessarily need to be all followed for all deployments, refer to the deployment guide to know which ones are important.
For a production deployment, it is crucial to change the default keys and credentials.
Local Test Deployment
Deployment of profile test-local-3nodes.
This deployment profile comes with default pre-generated keys and default passwords. It is not meant to contain any real data nor be used in production. If you wish to do so, use instead the deployment profile.
This test profile deploys 3 MedCo nodes on a single machine for test purposes. It can be used either on your local machine, or any other machine to which you have access. The version of the docker images used are the latest released versions. This profile is for example used for the .
MedCo Stack Deployment
First step is to get the MedCo latest release and download the docker images. Adapt ${MEDCO_SETUP_DIR} to where you wish to install MedCo.
The default configuration of the deployment is suitable if the stack is deployed on your local host, and if you do not need to modify the default passwords. To change the default passwords check out this page. For the other settings, check out the following example of modifying the file ${MEDCO_SETUP_DIR}/deployments/test-local-3nodes/.env to reflect your configuration. For example:
MEDCO_NODE_HOST should be the fully qualified domain name of the host, MEDCO_NODE_HTTP_SCHEME should be http or https.
If you enable HTTPS, follow HTTPS Configuration to set up the needed certificates.
Final step is to run the nodes, all three will run simultaneously:
Wait some time for the initialization of the containers to be done (up to the message: “i2b2-medco-srv… - Started x of y services (z services are lazy, passive or on-demand)”), this can take up to 10 minutes. For the subsequent runs, the startup will be faster. In order to stop the containers, hit Ctrl+C in the active window.
You can use the command docker-compose up -d instead to run MedCo in the background and thus not keeping the console captive. In that case use docker-compose stop to stop the containers.
Keycloak Configuration
Only needed if you are deploying somewhere else than your local host. Otherwise the default configuration will work fine.
In order to test that the local test deployment of MedCo is working, access Glowing Bear in your web browser at http(s)://${MEDCO_NODE_HOST} and use the default credentials specified in Keycloak user management. If you are new to Glowing Bear you can watch the Glowing Bear user interface walkthrough video. You can also use the CLI client to perform tests.
By default MedCo loads a specific test data, refer to Description of the default test data for expected results to queries. To load a dataset, follow the guide Loading Data. To load some additional test data by performing a simple data loading you can execute the following:
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.
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 first 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.
Resulting configuration for the authentication flow.
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
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.
Resulting configuration for the identity provider.
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.
Resulting configuration for the username mapper.
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.
Resulting configuration.
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/.
Example configuration for the basic resource information.
2. Descriptive Information
Example configuration for the descriptive information.
3. Contacts
Example configuration for the 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
Example configuration for the service locations.
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.
Example configuration for the certificates.
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.
Example configuration for the requested attributes.
7. Intended Audience and Interfederation
Example configuration for the intended audience.
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.
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 several 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 users
They all have the password test and have different authorizations that are obvious from their names.
User test: this user has all the authorizations to run all types of MedCo explore queries. it will default to the highest authorization being patient_list.
User test_explore_count_global
User test_explore_count_global_obfuscated
User test_explore_count_per_site
User test_explore_count_per_site_obfuscated
User test_explore_count_per_site_shuffled
User test_explore_count_per_site_shuffled_obfuscated
User test_explore_patient_list
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):
Deployment Profile
Valid Redirect URIs
test-local-3nodes
http(s)://<node domain name>/*
test-network + prod-network
https://<node domain name>/*
dev-local-3nodes
http://localhost:4200/*
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
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.
These pages explain how to deploy MedCo in different scenarios.
Each deployment scenario corresponds to a deployment profile, as described below. All these instructions use the deployment scripts from the repository.
If you are new to MedCo…
… and want to try to deploy the system on a single machine to test it, you should should follow the guide.
… and want to create or join a MedCo network, you should follow the guide.
… and want to develop around MedCo, you should follow the
Priority: 100
guide.
Deployment Profiles
A deployment profile is composed of two things:
deployment files medco/deployments/<profile name>/: docker-compose file and parameters like ports to expose, log level, etc.
configuration files medco/deployments/<profile name>/configuration/: files mounted in the docker containers, containing the cryptographic keys, the certificates, etc.
Some profiles are provided by default, for development or testing purposes. Those should not be used in a production scenario with real data, as the private keys are set by default, thus not private. Other types of profiles must generated using the script in medco/scripts/network-profile-tool/.
This profile deploys an arbitrary set of MedCo nodes independently in different machines that together form a MedCo network. This deployment assumes each node is deployed in a single dedicated machine. All the machines have to be reachable between each other. Nodes should agree on a network name and individual indexes beforehand (to be assigned a unique ID).
The next set of steps must be fully executed individually by each node of the network.
Pre-requisites
First step is to get the MedCo Deployment latest release at each node. Adapt ${MEDCO_SETUP_DIR} to where you wish to install MedCo.
Generation of the deployment Profile
Next the compose and configuration profiles must be generated using a script, executed in two steps.
Step 1: each node generates its keys and certificates, and shares its public information with the other nodes
Step 2: each node collects the public keys and certificates of the all the other nodes
Step 1
For step 1, the network name ${MEDCO_SETUP_NETWORK_NAME} should be common to all the nodes. ${MEDCO_SETUP_NODE_DNS_NAME} corresponds to the machine domain name where the node is being deployed. As mentioned before the different parties should have agreed beforehand on the members of the network, and assigned an index ${MEDCO_SETUP_NODE_IDX} to each different node to construct its UID (starting from 0, to n-1, n being the total number of nodes).
This script will generate the compose profile and part of the configuration profile, including a file srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz. This file should be shared with the other nodes, and all of them need to place it in their configuration profile folder (${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}/configuration).
Step 2
Before proceeding to this step, you need to have gathered all the files srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz from the persons deploying MedCo on the other nodes.
Once all nodes have shared their srv${MEDCO_SETUP_NODE_IDX}-public.tar.gz file with all other nodes, step 2 can be executed:
At this point, it is possible to edit the default configuration generated in ${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}/.env This is needed in order . When editing this file, be careful to change only the passwords and not the other values.
The deployment profile is now ready to be used.
MedCo Stack Deployment
Next step is to download the docker images and run the node:
Wait some time for the initialization of the containers to be done, this can take up to 10 minutes. For the subsequent runs, the startup will be faster. You can use make stop to stop the containers and make down to delete them.
Keycloak Configuration
You will need to follow two sets of instruction to make Keycloak functional and be able to log in. and then:
Test the deployment
Note that by default the certificates generated by the script are self-signed and thus, when using Glowing Bear, the browser will issue a security warning. To use your own valid certificates, see . If you wish anyway to use the self-signed certificates, you will need to visit individually the page of Glowing Bear of all nodes in your browser, and select to trust the certificate.
The database is pre-loaded with some encrypted test data using a key that is pre-generated from the combination of all the participating nodes’ public keys. For the network deployment profile this data will not be correctly encrypted, since the public key of each node is generated independently, and, as such, the data must be re-loaded before being able to test the system successfully.
Run first the MedCo loader (see ) to load some data and be able to test this deployment. Or to load some test data by performing a simple data loading you can execute the following:
Then access Glowing Bear in your web browser at https://${MEDCO_SETUP_NODE_DNS_NAME} and use the default credentials specified in . If you are new to Glowing Bear you can watch the video. You can also use the to perform tests.
cd "${MEDCO_SETUP_DIR}/scripts/network-profile-tool"
bash step2.sh ${MEDCO_SETUP_NETWORK_NAME} ${MEDCO_SETUP_NODE_IDX}
cd "${MEDCO_SETUP_DIR}/deployments/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}"
make pull
make up
make load_test_data
HTTPS Configuration
HTTPS is supported for the profiles test-local-3nodes and test-network.
Certificate
The certificates are held in the configuration profile folder (e.g, ${MEDCO_SETUP_DIR}/deployments/test-local-3nodes/configuration):
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 .
Then edit the file .env from the compose profile, replace the http with https, and restart the deployment.
Configure HTTPS for the Network Deployment
For this profile, HTTPS is mandatory. The profile generation script generates and uses 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.
