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
Name | Description | Default Value |
---|---|---|
VERSION | Version of this instance. | - |
LOG_LEVEL | Log 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
Name | Description | Default Value |
---|---|---|
SERVER_NAME | Hostname for the server, e.g. example.de | - |
SERVER_PORT | Port for the server. | 443 |
KEYCLOAK_SERVER_NAME | URL of the Keycloak server, .e.g https://keycloak.example. Avoid trailing slashes. | - |
KEYCLOAK_SERVER_TYPE | Keycloak server type (Internal or External ). Internal is not supported for productive use. | External |
KEYCLOAK_ADMIN_PW | Password for the Keycloak admin user (required if KEYCLOAK_SERVER_TYPE is set to Internal ) | - |
DOCKER_REGISTRY_PREFIX_DOCKERHUB | Docker registry prefix | see below |
DOCKER_REGISTRY_PREFIX_QUAYIO | Docker registry prefix | see below |
DOCKER_REGISTRY_PREFIX_GITLAB | Docker registry prefix | see 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
Name | Description | Default Value |
---|---|---|
GF_SECURITY_ADMIN_PASSWORD | Grafana admin password. | - |
PROMETHEUS_GLOBAL_SCRAPE_INTERVAL | Prometheus scrape interval. | 120s |
MONITORING_METRIC_RESOURCE_COUNT_PATIENT | Number of patients. | true |
MONITORING_METRIC_RESOURCE_COUNT_ENCOUNTER | Number of encounters. | true |
MONITORING_METRIC_RESOURCE_COUNT_REFERENCE | Number of other resources. | true |
MONITORING_METRIC_PSEUDONYM_COUNT_PATIENT | Number of patient pseudonyms per target system. | true |
MONITORING_METRIC_PSEUDONYM_COUNT_ENCOUNTER | Number of encounter pseudonyms per target system. | true |
MONITORING_METRIC_PSEUDONYM_COUNT_REFERENCE | Number of reference pseudonyms per target system. | true |
MONITORING_METRIC_DEPSN_COUNT | Number of DEPSN operations. | true |
MONITORING_SCHEDULING_ENABLED | Indicates if scheduling for multi gauge metrics is enabled. | true |
MONITORING_SCHEDULING_DELAY | Delay 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:
Name | Description | Default Value |
---|---|---|
MAIL_SERVICE_ENABLED | Enable or disable mail service globally. | false |
MAIL_SERVICE_HOST | Mail server host name, e.g. postout.lrz.de. | - |
MAIL_SERVICE_PORT | Mail server port, e.g. 587. | - |
MAIL_SERVICE_USERNAME | Username associated with the mail server account. | - |
MAIL_SERVICE_PASSWORD | Password associated with the mail server account. | - |
MAIL_SERVICE_FROM_EMAIL | Email address associated with the mail server account. | - |
MAIL_SERVICE_TO_EMAIL | Recipients; 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
Name | Description | Default Value |
---|---|---|
SPRING_SECURITY_USER_NAME | Spring security user name. | - |
SPRING_SECURITY_USER_PW | Spring security password. | - |
TC_INTERFACE_CLIENT_SECRET | Client secret of the Keycloak client trustcenter-interface . Needs to be looked up in the Keycloak server defined in KEYCLOAK_SERVER_NAME . | - |
PSN_PARALLELISM_LEVEL | Number 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
Name | Description | Default Value |
---|---|---|
LEVEL_1_PSNS_ENABLE_MASTERDATA | Flag indicating whether to process masterdata. | true |
LEVEL_1_PSNS_LIMIT | Limit on the search result, the number of entries that will maximally be shown in the GUI. | 30 |
LEVEL_1_PSNS_ALPHABETS | Alphabets used for pseudonym generation, e.g. “system-1:10:ABC;system-2:15:123ABC”. | - |
LEVEL_1_PSNS_DB_UNAME | Database username for Level-1 PSN Service. | - |
LEVEL_1_PSNS_DB_PW | Database password for Level-1 PSN Service. | - |
LEVEL_1_PSNS_DB_ENC_PW | Encryption password for the database in Level-1 PSN Service. | - |
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLED | Flag indicating whether pseudonyms should be encrypted by default if the target system is unknown. | true |
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRING | String containing target systems for which pseudonym encryption should be enabled or disabled. | - |
LEVEL_1_BF_ENABLED | Flag indicating if Bloomfilter is enabled. | false |
LEVEL_1_BF_BALANCED_SEED | Balanced seed for Bloomfilter. | - |
LEVEL_1_BF_BIRTH_DATE_SEED | Birth date seed for Bloomfilter. | - |
LEVEL_1_BF_BITS_PER_NGRAM | Bits per ngram for Bloomfilter. | - |
LEVEL_1_BF_FIRST_NAME_SEED | First name seed for Bloomfilter. | - |
LEVEL_1_BF_GENDER_SEED | Gender seed for Bloomfilter. | - |
LEVEL_1_BF_LAST_NAME_SEED | Last name seed for Bloomfilter. | - |
LEVEL_1_BF_LENGTH | Length 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
Name | Available since |
---|---|
VERSION | v3.0.0 |
LOG_LEVEL | v5.1.0 |
SERVER_NAME | v1.0.0 |
SERVER_PORT | v1.0.0 |
KEYCLOAK_SERVER_NAME | v1.1.0 |
KEYCLOAK_SERVER_TYPE | v1.1.0 |
KEYCLOAK_ADMIN_PW | v1.2.1 |
DOCKER_REGISTRY_PREFIX | v1.3.0 |
KEYCLOAK_CLIENT_CLIENT_ID_FOR_INTERFACE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_INTERFACE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_PSN_SERVICE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_DEPSN_SERVICE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_1_WEBAPP | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_PSN_SERVICE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_DEPSN_SERVICE | v4.0.0 |
KEYCLOAK_CLIENT_RESOURCE_ID_FOR_LEVEL_2_WEBAPP | v4.0.0 |
GF_SECURITY_ADMIN_PASSWORD | v5.0.0 |
PROMETHEUS_GLOBAL_SCRAPE_INTERVAL | v5.0.0 |
MONITORING_METRIC_RESOURCE_COUNT_PATIENT | v5.0.0 |
MONITORING_METRIC_RESOURCE_COUNT_ENCOUNTER | v5.0.0 |
MONITORING_METRIC_RESOURCE_COUNT_REFERENCE | v5.0.0 |
MONITORING_METRIC_PSEUDONYM_COUNT_PATIENT | v5.0.0 |
MONITORING_METRIC_PSEUDONYM_COUNT_ENCOUNTER | v5.0.0 |
MONITORING_METRIC_PSEUDONYM_COUNT_REFERENCE | v5.0.0 |
MONITORING_METRIC_DEPSN_COUNT | v5.0.0 |
MONITORING_SCHEDULING_ENABLED | v5.0.0 |
MONITORING_SCHEDULING_DELAY | v5.0.0 |
MAIL_SERVICE_ENABLED | v5.1.0 |
MAIL_SERVICE_HOST | v5.1.0 |
MAIL_SERVICE_PORT | v5.1.0 |
MAIL_SERVICE_USERNAME | v5.1.0 |
MAIL_SERVICE_PASSWORD | v5.1.0 |
MAIL_SERVICE_FROM_EMAIL | v5.1.0 |
MAIL_SERVICE_TO_EMAIL | v5.1.0 |
SPRING_SECURITY_USER_NAME | v1.1.0 |
SPRING_SECURITY_USER_PW | v1.1.0 |
TC_INTERFACE_CLIENT_SECRET | v1.1.0 |
PSN_PARALLELISM_LEVEL | v5.0.0 |
LEVEL_1_PSNS_ENABLE_MASTERDATA | v1.1.0 |
LEVEL_1_PSNS_LIMIT | v1.1.0 |
LEVEL_1_PSNS_ALPHABETS | v2.1.0 |
LEVEL_1_PSNS_DB_UNAME | v1.1.0 |
LEVEL_1_PSNS_DB_PW | v1.1.0 |
LEVEL_1_PSNS_DB_ENC_PW | v1.1.0 |
LEVEL_1_PSNS_ENC_DEFAULT_CASE_ENABLED | v3.0.0 |
LEVEL_1_PSNS_ENC_TARGET_SYSTEMS_STRING | v3.0.0 |
LEVEL_1_BF_ENABLED | v2.1.0 |
LEVEL_1_BF_BALANCED_SEED | v2.1.0 |
LEVEL_1_BF_BIRTH_DATE_SEED | v2.1.0 |
LEVEL_1_BF_BITS_PER_NGRAM | v2.1.0 |
LEVEL_1_BF_FIRST_NAME_SEED | v2.1.0 |
LEVEL_1_BF_GENDER_SEED | v2.1.0 |
LEVEL_1_BF_LAST_NAME_SEED | v2.1.0 |
LEVEL_1_BF_LENGTH | v2.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'