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 public demo.

MedCo Stack Deployment

First step is to get the MedCo Deployment 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 . For the other settings, check out the following example of modifying the file ${MEDCO_SETUP_DIR}/compose-profiles/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.

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.

Keycloak Configuration

Follow the instructions for to be able to login in Glowing Bear.

Test the deployment

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 . If you are new to Glowing Bear you can watch the video. You can also use the to perform tests.

By default MedCo loads a specific test data, refer to for expected results to queries. To load a dataset, follow the guide .

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.

Resources

• MedCo software repositories

  • (forked from )

• Other resources

• Deprecated repositories

  • (forked from )

Contact

For assistance with deploying MedCo or any other technical questions, send an email at or any of the contributors.

• (Privacy and Security Software Engineer, EPFL) -

• (Privacy and Security Software Engineer, EPFL) -

• (Privacy and Security Software Engineer, EPFL) -

License

MedCo is licensed under a End User Software License Agreement (‘EULA’) for non-commercial use. If you need more information, please contact us.

We recommend the following specifications for running MedCo:

• Network Bandwidth: >100 Mbps (ideal), >10 Mbps (minimum), symmetrical

• Ports Opening and IP Restrictions: see Network Architecture

• Hardware

  • CPU: 8 cores (ideal), 4 cores (minimum)

  • RAM: >16 GB (ideal), >8GB (minimum)

• Software

  • OS: Any flavor of Linux, physical or virtualized (tested with Ubuntu 16.04, 18.04, Fedora 29)

  • OpenSSL

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.

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.

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

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:

v1.0.0 - 31th March 2020

• First stable version

• Externally reviewed and pen-tested

• Bug fixes and enhancements

v0.3.1 - 6th March 2020

• Several bug fixes and enhancements

v0.3.0 - 11th February 2020

• Many corrections to comply with security reviews

• Architecture changes: removal of PICSURE, new implementation of genomic annotations querying

• Keycloak auto-provisioning

v0.2.1 - 15th August 2019

• Implementation of additional query types (patient list, locally obfuscated count, global count, shuffled count)

• Implementation of OIDC-based authorization model

• Implementation of CLI client

v0.2.0 - 3rd May 2019

• Architecture revisit

• Replaced medco-i2b2-cell by medco-connector

• Upgrades (IRCT v1.4 to PICSURE v2.0, Onet suite v3, Keycloak, Nginx, PHP)

v0.1.1 - 23rd January 2019

• Deployment for test purposes on several machines

• Enhancements of documentation and deployment infrastructure

• Nginx reverse proxy with HTTPS support

v0.1.0 - 1st December 2018

First public release of MedCo, running with i2b2 v1.7, PIC-SURE/IRCT v1.4 and centralized OpenID Connect authentication. Deployment for development and test purpose on a single machine.

Each deployment scenario corresponds to a deployment profile, as described below. All these instructions use the deployment scripts from the medco 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 Local Test Deployment guide.

… and want to create or join a MedCo network, you should follow the Network Deployment guide.

… and want to develop around MedCo, you should follow the Local Development Deployment 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/.

The different profiles are the following:

test-local-3nodes ()

• for test on a single machine (used by the MedCo live demo)

• 3 nodes on any host

• using the latest release of the source codes

network ()

• for test or production deployment on several different hosts

• a single node on a host part of a MedCo network

• using the latest release of the source codes

dev-local-3nodes ()

• for software development

• 3 nodes on the local host

• using development version of source codes

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.

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

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}/configuration-profiles/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}).

Step 2

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}/configuration-profiles/test-network-${MEDCO_SETUP_NETWORK_NAME}-node${MEDCO_SETUP_NODE_IDX}/.env This is needed if you want . 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 docker-compose stop to stop the containers and docker-compose 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

Run first the MedCo loader (see ) to load some data and be able to test this deployment. 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.

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 .

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

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.

The current version of the loader offers two different loading alternatives: (v0) loading of clinical and genomic data based on MAF datasets; and (v1) loading of generic i2b2 data. Currently these two loaders support each one dataset:

• v0: a genomic dataset (tcga_cbio publicly available in cBioPortal)

• v1: the i2b2 demodata.

Future releases of this software will allow for other arbitrary data sources, given that they follow a specific structure (e.g. BAM format).

Pre-Requisite: Download test data

From the medco-deployment folder, execute the resources/data/download.sh script to download the test datasets.

Dummy Generation

The provided example data set files come with dummy data pre-generated. Those data are random dummy entries whose purpose is to prevent frequency attacks. In a future release, the generation will be done dynamically by the loader.

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 .

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.

The v1 loader expects an already existing i2b2 database (in .csv format) that will be converted in a way that is compliant with the MedCo data model. This involves encrypting and deterministically tagging some of the data.

List of input (‘original’) files:

• all i2b2metadata files (e.g. i2b2.csv)

• dummy_to_patient.csv

• patient_dimension.csv

• visit_dimension.csv

• concept_dimension.csv

• modifier_dimension.csv

• observation_fact.csv

• table_access.csv

How to use

The following examples show you how to load data into a running MedCo deployment. Adapt accordingly the commands your use-case.

Examples

Loading the three nodes on the dev-local-3nodes profile

Loading one node on a network-test profile

Explanation of the command's arguments

Test that the loading was successful

To check that it is working you can query for:

-> Diagnoses -> Neoplasm -> Benign neoplasm -> Benign neoplasm of breast

You should obtain 2 matching subjects.

The v0 loader expects an ontology, with mutation and clinical data in the MAF format. As the ontology data you must use ${MEDCO_SETUP_DIR}/resources/data/genomic/tcga_cbio/clinical_data.csv and ${MEDCO_SETUP_DIR}/resources/data/genomic/tcga_cbio/mutation_data.csv. For clinical data you can keep using the same two files or a subset of the data (e.g. 8_clinical_data.csv). More information about how to generate sample data files can be found below. After the following script is executed all the data is encrypted and deterministically tagged in compliance with the MedCo data model.

How to use

The following examples show you how to load data into a running MedCo deployment. Adapt accordingly the commands your use-case.

Examples

Loading the three nodes on the dev-local-3nodes profile

Loading one node on a network-test profile

Explanation of the command's arguments

Test that the loading was successful

To check that it is working you can query for:

-> MedCo Gemomic Ontology -> Gene Name -> BRPF3

For the small dataset 8_xxxx you should obtain 3 matching subjects (one at each site).

MedCo provides a client command-line interface (CLI) to interact with the medco-connector APIs.

Prerequisites

To use the CLI, you must first follow one of the deployment guides. However, the version of the CLI documented here is the one shipped with the Local Development Deployment.

How to use

To show the CLI manual, run:

query

You can use this command to query the MedCo network.

This is the syntax of an example query using the pre-loaded .

You will get something like that:

genomic-annotations-get-values

You can use this command to get the values of the genomic annotations that MedCo nodes make available for queries.

To do some tests, you may want to .

Then, for example, if you want to know which genomic annotations of type "protein_change" containing the string "g32" are available, you can run:

You will get:

genomic-annotations-get-variants

You can use this command to get the variant ID of a certain genomic annotation.

To do some tests, you may want to .

Then, for example, if you want to know the variant ID of the genomic annotation "HTR5A" of type "hugo_gene_symbol" with zygosity "heterozygous" or "homozygous", you can run:

You will get:

External Entities

Entities that need to connect to a machine running MedCo can be categorized as follow:

• System administrators: Persons administrating the MedCo node. Likely to remain inside the clinical site internal network.

• End-users: Researchers using MedCo to access the shared. Likely to remain inside the clinical site internal network.

• Other MedCo nodes: MedCo nodes belonging to other clinical sites of the network.

Firewall Ports Opening

The following ports should be accessible by the listed entities, which makes IP address white-listing possible:

• Port 22, 5432 (TCP): System Administrators

• Port 80 (TCP): End-Users (HTTP automatic redirect to HTTPS (443))

• Port 443 (TCP): System Administrators, End-Users, Other MedCo Nodes

Containers

medco-connector

Docker-related issues

Changing the Docker default address pool

This deployment profile deploys 3 MedCo nodes on a single machine for development purposes. It is meant to be used only on your local machine, i.e. localhost. The tags of the docker images used are all dev, i.e. the ones built from the development version of the different source codes. They are available either through Docker Hub, or built locally from the sources of each component.

The default data loaded in MedCo is a small artificially generated dataset, appropriate to test a fresh deployment. The same data is replicated on all the nodes. Note that as of now it is encrypted using the test keys, i.e. the ones used for deployment profiles dev-local-3nodes and test-local-3nodes.

It contains 4 patients: 1 (real), 2 (real), 3 (real), 4 (dummy).

And 3 concepts: 1, 2, and 3.

The observation fact contains the following entries:

Administration with PgAdmin

PgAdmin can be accessed through http(s)://<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). Note that PgAdmin is not included in the production deployments.