Configuration

Environment variables

The configuration is handled via one single .env file. A template file is available here. This section gives an overview of all available configuration parameters.

Basic Configuration

NameDescriptionDefault Value
VERSIONVersion of this instance.-
LOG_LEVELLog level for application logging. This only applies to self-developed code.INFO
Template with default values
##### Version of this instance.
VERSION=5.2.0-RELEASE
LOG_LEVEL=INFO

Server Configuration

NameDescriptionDefault Value
SERVER_NAMEHostname for the server, e.g. example.de-
SERVER_PORTPort for the server.443
KEYCLOAK_SERVER_NAMEURL of the Keycloak server, .e.g https://keycloak.example. Avoid trailing slashes.-
KEYCLOAK_SERVER_TYPEKeycloak server type (Internal or External). Internal is not supported for productive use.External
KEYCLOAK_ADMIN_PWPassword for the Keycloak admin user (required if KEYCLOAK_SERVER_TYPE is set to Internal)-
DOCKER_REGISTRY_PREFIX_DOCKERHUBDocker registry prefixsee below
DOCKER_REGISTRY_PREFIX_QUAYIODocker registry prefixsee below
DOCKER_REGISTRY_PREFIX_GITLABDocker registry prefixsee below
Template with default values
###################################################################
###################### Server configuration #######################
###################################################################

##### Hostname
# Example: entici.med.tum.de
SERVER_NAME=

##### Port
SERVER_PORT=443

##### URL of the keycloak server
# Example: https://keycloak.example
# Note: Avoid trailing slashes!
KEYCLOAK_SERVER_NAME=

#### Keycloak server type (Internal or External)
# Default: External.
# Note: Use Internal only for testing purposes.
KEYCLOAK_SERVER_TYPE=External

##### Password for the keycloak admin user (must be set if 'KEYCLOAK_SERVER_TYPE'==Internal)
KEYCLOAK_ADMIN_PW=

##### Docker registry prefix
DOCKER_REGISTRY_PREFIX_DOCKERHUB=docker.io
DOCKER_REGISTRY_PREFIX_QUAYIO=quay.io
DOCKER_REGISTRY_PREFIX_GITLAB=registry.gitlab.com/entici/public

Keycloak Configuration

For testing purposes, an optional Keycloak server has been integrated into this deployment package. In order to enable the internal Keycloak server, apply the following configuration:

#### 'Internal' when using internal, 'External' when using external keycloak server
KEYCLOAK_SERVER_TYPE=Internal

To avoid known issues (especially for internal Keycloak instances), check the Troubleshooting section.

The configuration of a realm called trustcenter has to be provided via /config/keycloak/trustcenter-realm.json. More information about how to use a predefined configuration file or manually create a realm configuration can be found here.

The following parameter values match the predefined realm and thus in most cases can be kept as is. They might have to be changed in case the realm is configured manually.

KEYCLOAK_CLIENT_CLIENT_ID_FOR_INTERFACE=trustcenter-interface
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_INTERFACE=trustcenter-facade
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_PSN_SERVICE=backend-entitylist
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_DEPSN_SERVICE=entitylist-depsn-service
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_WEBAPP=entitylist-webapp

Monitoring Configuration

NameDescriptionDefault Value
GF_SECURITY_ADMIN_PASSWORDGrafana admin password.-
PROMETHEUS_GLOBAL_SCRAPE_INTERVALPrometheus scrape interval.120s
MONITORING_METRIC_RESOURCE_COUNT_PATIENTNumber of patients.true
MONITORING_METRIC_RESOURCE_COUNT_ENCOUNTERNumber of encounters.true
MONITORING_METRIC_RESOURCE_COUNT_REFERENCENumber of other resources.true
MONITORING_METRIC_PSEUDONYM_COUNT_PATIENTNumber of patient pseudonyms per target system.true
MONITORING_METRIC_PSEUDONYM_COUNT_ENCOUNTERNumber of encounter pseudonyms per target system.true
MONITORING_METRIC_PSEUDONYM_COUNT_REFERENCENumber of reference pseudonyms per target system.true
MONITORING_METRIC_DEPSN_COUNTNumber of DEPSN operations.true
MONITORING_SCHEDULING_ENABLEDIndicates if scheduling for multi gauge metrics is enabled.true
MONITORING_SCHEDULING_DELAYDelay in milliseconds for monitoring scheduling.1000
Template with default values
# Grafana admin password
GF_SECURITY_ADMIN_PASSWORD=

# Prometheus scrape interval
PROMETHEUS_GLOBAL_SCRAPE_INTERVAL=120s

############################################## Simple Gauge Metrics
# Number of patients
MONITORING_METRIC_RESOURCE_COUNT_PATIENT=true
# Number of encounter
MONITORING_METRIC_RESOURCE_COUNT_ENCOUNTER=true
# Number of other resources
MONITORING_METRIC_RESOURCE_COUNT_REFERENCE=true

############################################### Multi Gauge metrics

# Number of patient pseudonyms per target system
MONITORING_METRIC_PSEUDONYM_COUNT_PATIENT=true
# Number of encounter pseudonyms per target system
MONITORING_METRIC_PSEUDONYM_COUNT_ENCOUNTER=true
# Number of reference pseudonyms per target system
MONITORING_METRIC_PSEUDONYM_COUNT_REFERENCE=true
# Number of depsn operations
MONITORING_METRIC_DEPSN_COUNT=true

# Required for multi gauge metrics
MONITORING_SCHEDULING_ENABLED=true
MONITORING_SCHEDULING_DELAY=1000

Mail Service Configuration

The mail service allows to automatically send emails in case an unforeseen error occurred. The mail service has to be configured via the following parameters:

NameDescriptionDefault Value
MAIL_SERVICE_ENABLEDEnable or disable mail service globally.false
MAIL_SERVICE_HOSTMail server host name, e.g. postout.lrz.de.-
MAIL_SERVICE_PORTMail server port, e.g. 587.-
MAIL_SERVICE_USERNAMEUsername associated with the mail server account.-
MAIL_SERVICE_PASSWORDPassword associated with the mail server account.-
MAIL_SERVICE_FROM_EMAILEmail address associated with the mail server account.-
MAIL_SERVICE_TO_EMAILRecipients; a list of email addresses in the correct format, separated by ‘,’, e.g. “user1@tum.de,user2@tum.de”.-
Template with default values
# Enable or disable mail service globally
MAIL_SERVICE_ENABLED=false
# Mail server host name, e.g. postout.lrz.de
MAIL_SERVICE_HOST=
# Mail server port, e.g. 587
MAIL_SERVICE_PORT=
# Username associated with the mail server account
MAIL_SERVICE_USERNAME=
# Password associated with the mail server account
MAIL_SERVICE_PASSWORD=
# Email address associated with the mail server account
MAIL_SERVICE_FROM_EMAIL=
# Recipients; a list of email addresses in the correct format, separated by ',', e.g. "user1@tum.de,user2@tum.de"
MAIL_SERVICE_TO_EMAIL=

Program Configuration

NameDescriptionDefault Value
SPRING_SECURITY_USER_NAMESpring security user name.-
SPRING_SECURITY_USER_PWSpring security password.-
TC_INTERFACE_CLIENT_SECRETClient secret of the Keycloak client trustcenter-interface. Needs to be looked up in the Keycloak server defined in KEYCLOAK_SERVER_NAME.-
PSN_PARALLELISM_LEVELNumber of parallel threads used for pseudonymization.
Minimum: 1
Maximum: \(0.5*num\_processors\)
8
Template with default values
#### Spring security user
SPRING_SECURITY_USER_NAME=

#### Spring security password
SPRING_SECURITY_USER_PW=

#### Client secret of the keycloak client 'trustcenter-interface'
# Needs to be looked up in the keycloak server defined in 'KEYCLOAK_SERVER_NAME'
TC_INTERFACE_CLIENT_SECRET=

#### Number of parallel threads used for pseudonymization
# Minimum: 1
# Default: 8
# Maximum: 0.5*#available processors
PSN_PARALLELISM_LEVEL=

Entity List Configuration

NameDescriptionDefault Value
LEVEL_1_PSNS_ENABLE_MASTERDATAFlag indicating whether to process masterdata.true
LEVEL_1_PSNS_LIMITLimit on the search result, the number of entries that will maximally be shown in the GUI.30
LEVEL_1_PSNS_ALPHABETSAlphabets used for pseudonym generation, e.g. “system-1:10:ABC;system-2:15:123ABC”.-
LEVEL_1_PSNS_DB_UNAMEDatabase username for Level-1 PSN Service.-
LEVEL_1_PSNS_DB_PWDatabase password for Level-1 PSN Service.-
LEVEL_1_PSNS_DB_ENC_PWEncryption password for the database in Level-1 PSN Service.-
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLEDFlag indicating whether pseudonyms should be encrypted by default if the target system is unknown.true
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRINGString containing target systems for which pseudonym encryption should be enabled or disabled.-
LEVEL_1_BF_ENABLEDFlag indicating if Bloomfilter is enabled.false
LEVEL_1_BF_BALANCED_SEEDBalanced seed for Bloomfilter.-
LEVEL_1_BF_BIRTH_DATE_SEEDBirth date seed for Bloomfilter.-
LEVEL_1_BF_BITS_PER_NGRAMBits per ngram for Bloomfilter.-
LEVEL_1_BF_FIRST_NAME_SEEDFirst name seed for Bloomfilter.-
LEVEL_1_BF_GENDER_SEEDGender seed for Bloomfilter.-
LEVEL_1_BF_LAST_NAME_SEEDLast name seed for Bloomfilter.-
LEVEL_1_BF_LENGTHLength of the Bloomfilter.-
Template with default values
###################################################################
###################### Level-1 PSN Service ########################
###################################################################

#### Flag indicating whether to process masterdata
# Note: In the default case, this flag should be set to 'true'. In that case, in addition
# to identifiers, patient masterdata will be stored. Only if this instance is to be used for
# second-level, or project-specific, pseudonymization, should this flag be set to 'false'.
LEVEL_1_PSNS_ENABLE_MASTERDATA=

#### Limit on the search result, the number of entries that will maximally be shown in the GUI
LEVEL_1_PSNS_SLIMIT=30

#### Alphabets used for pseudonym generation
# The string contains alphabets separated by ';'. The alphabets are comprised of the
# three components 'system', 'length' and 'chars' separated by ':'.
# Example: "system-1:10:ABC;system-2:15:123ABC"
LEVEL_1_PSNS_ALPHABETS=

############################ Database #############################

#### Username
LEVEL_1_PSNS_DB_UNAME=

#### Password
LEVEL_1_PSNS_DB_PW=

#### Encryption password
LEVEL_1_PSNS_DB_ENC_PW=

###################### Transport encryption #######################

#### Flag indicating whether pseudonyms (created from 'v1/process') should
# be encrypted by default. This flag applies to queries sent to 'v1/process' without specifying
# a target system or in case the target system is unknown.
# IF set to true, a public key 'default.pubkey' has to be provided in '/config/keys/entitylist'
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLED=true
#### String containing target system, for which pseudonym encryption should be enabled or disabled.
# Example: test-system;test-system-2 (systems have to be separated by semicolon.
# Important: IF a target system is specified here, a public key '<target-system>.pubkey' can be provided
# in '/config/keys/entitylist', which will then be used to encrypt the corresponding pseudonym. If no key
# is provided, encryption will be turned of for this target system.
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRING=

####################### Bloomfilter config ########################

LEVEL_1_BF_ENABLED=false
LEVEL_1_BF_BALANCED_SEED=
LEVEL_1_BF_BIRTH_DATE_SEED=
LEVEL_1_BF_BITS_PER_NGRAM=
LEVEL_1_BF_FIRST_NAME_SEED=
LEVEL_1_BF_GENDER_SEED=
LEVEL_1_BF_LAST_NAME_SEED=
LEVEL_1_BF_LENGTH=

Overview

NameAvailable since
VERSIONv3.0.0
LOG_LEVELv5.1.0
SERVER_NAMEv1.0.0
SERVER_PORTv1.0.0
KEYCLOAK_SERVER_NAMEv1.1.0
KEYCLOAK_SERVER_TYPEv1.1.0
KEYCLOAK_ADMIN_PWv1.2.1
DOCKER_REGISTRY_PREFIXv1.3.0
KEYCLOAK_CLIENT_CLIENT_ID_FOR_INTERFACEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_INTERFACEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_PSN_SERVICEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_DEPSN_SERVICEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_WEBAPPv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_PSN_SERVICEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_DEPSN_SERVICEv4.0.0
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_WEBAPPv4.0.0
GF_SECURITY_ADMIN_PASSWORDv5.0.0
PROMETHEUS_GLOBAL_SCRAPE_INTERVALv5.0.0
MONITORING_METRIC_RESOURCE_COUNT_PATIENTv5.0.0
MONITORING_METRIC_RESOURCE_COUNT_ENCOUNTERv5.0.0
MONITORING_METRIC_RESOURCE_COUNT_REFERENCEv5.0.0
MONITORING_METRIC_PSEUDONYM_COUNT_PATIENTv5.0.0
MONITORING_METRIC_PSEUDONYM_COUNT_ENCOUNTERv5.0.0
MONITORING_METRIC_PSEUDONYM_COUNT_REFERENCEv5.0.0
MONITORING_METRIC_DEPSN_COUNTv5.0.0
MONITORING_SCHEDULING_ENABLEDv5.0.0
MONITORING_SCHEDULING_DELAYv5.0.0
MAIL_SERVICE_ENABLEDv5.1.0
MAIL_SERVICE_HOSTv5.1.0
MAIL_SERVICE_PORTv5.1.0
MAIL_SERVICE_USERNAMEv5.1.0
MAIL_SERVICE_PASSWORDv5.1.0
MAIL_SERVICE_FROM_EMAILv5.1.0
MAIL_SERVICE_TO_EMAILv5.1.0
SPRING_SECURITY_USER_NAMEv1.1.0
SPRING_SECURITY_USER_PWv1.1.0
TC_INTERFACE_CLIENT_SECRETv1.1.0
PSN_PARALLELISM_LEVELv5.0.0
LEVEL_1_PSNS_ENABLE_MASTERDATAv1.1.0
LEVEL_1_PSNS_LIMITv1.1.0
LEVEL_1_PSNS_ALPHABETSv2.1.0
LEVEL_1_PSNS_DB_UNAMEv1.1.0
LEVEL_1_PSNS_DB_PWv1.1.0
LEVEL_1_PSNS_DB_ENC_PWv1.1.0
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLEDv3.0.0
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRINGv3.0.0
LEVEL_1_BF_ENABLEDv2.1.0
LEVEL_1_BF_BALANCED_SEEDv2.1.0
LEVEL_1_BF_BIRTH_DATE_SEEDv2.1.0
LEVEL_1_BF_BITS_PER_NGRAMv2.1.0
LEVEL_1_BF_FIRST_NAME_SEEDv2.1.0
LEVEL_1_BF_GENDER_SEEDv2.1.0
LEVEL_1_BF_LAST_NAME_SEEDv2.1.0
LEVEL_1_BF_LENGTHv2.1.0

Server Certificate

In order to use SSL, a server certificate has to be provided and configured.

In config/ssl, store:

  • the private key ssl.key
  • the server certificate ssl.crt
  • the certificate-chain chain.txt beginning with the server certificate

Untrusted Certificate Authorities

Untrusted CAs can be trusted by adding their certificates to config/bootstrap/certs. The certificate must be encoded in Base64 and have the file ending .crt.

Self-signed certificates may be generated using the following commands:

# Create certificate
openssl req -x509 -nodes -newkey rsa:2048 -keyout ./config/ssl/ssl.key -out ./config/ssl/ssl.crt
# Create empty chain.txt
cp ./config/ssl/ssl.crt ./config/ssl/chain.txt
# Add certificate to the certificate bootstrap pipeline
cp ./config/ssl/ssl.crt ./config/bootstrap/certs/ssl.crt

Transport encryption

After pseudonymization using the REST interface v1/process[?targetSystem=<target-system>], resulting pseudonyms can be encrypted for transport. If no target system is specified in the query, the default case applies which is configured via the following parameter:

# Level 1 pseudonym encryption default case
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLED=true

If the parameter is set to true, a public key default.pubkey has to be provided in /config/keys/entitylist.

If a target system is specified in the query, transport encryption can be configured via the following parameter:

# Level 1 target systems
# Example: test-system-1,test-system-2
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRING=

The parameter is a string containing target systems separated by semicolon. For each target system, encryption can be turned on by providing a public key <target-system>.pubkey in /config/keys/entitylist. If no key is provided, encryption will be disabled for this target system.

How to generate a public/private key pair

[Method 1] Using component-crypto:

In order to generate a pair of public and private keys the project component-crypto may be used. Run the test testCreateKeys() in the class EncryptorText, which will generate a public.key and private.key in a folder /out. Further information about how to use the keys for encrypting and decrypting texts can be found here.

[Method 2] Using OpenSSL:

You can create a pair of public and private keys with OpenSSL like this:

# define paths
generated_keypair_file=./keypair.pem
private_key_file=./private.key
public_key_file=./public.key

# generate keypair
openssl genpkey -algorithm RSA -out $generated_keypair_file -pkeyopt rsa_keygen_bits:2048 >/dev/null 2>&1
# extract public key
openssl rsa -pubout -in $generated_keypair_file -out $public_key_file >/dev/null 2>&1
# extract private key
openssl pkcs8 -topk8 -in $generated_keypair_file -nocrypt -out $private_key_file >/dev/null 2>&1

# extract variables for .env file
# format: remove both "-----" lines and linebreaks to obtain the desired keys
echo "Public key is:"
cat $public_key_file | grep -Ev -e '-----(BEGIN|END) PUBLIC KEY-----' | tr -d '\n'
echo

echo

echo "Private key is:"
cat $private_key_file | grep -Ev -e '-----(BEGIN|END) PRIVATE KEY-----' | tr -d '\n'
echo

Cryptographic Keys in Configuration Variables

Private and public keys need to be stored in .env variables (e.g. LEVEL_1_PSNS_PSN_ENC_PUB_KEY). Usually, such keys are initially stored in a key file that starts/ends with the lines -----(BEGIN|END) PRIVATE KEY----- or -----(BEGIN|END) PUBLIC KEY-----. In order to set the .env variable to your key, you need to remove these lines and all linebreaks before assigning the value to the variable. For instance, when dealing with a public key, the value of the variable can be obtained by:

cat $your_public_key_file | grep -Ev -e '-----(BEGIN|END) PUBLIC KEY-----' | tr -d '\n'