diff --git a/docs/src/.vuepress/layouts/PageLayout.vue b/docs/src/.vuepress/layouts/PageLayout.vue index e7d293fbb..ef86a03e2 100644 --- a/docs/src/.vuepress/layouts/PageLayout.vue +++ b/docs/src/.vuepress/layouts/PageLayout.vue @@ -55,6 +55,7 @@ function navigateToNewVersion() {
diff --git a/docs/src/.vuepress/public/download/dsf_bpe_2_0_0-RC1.tar.gz b/docs/src/.vuepress/public/download/dsf_bpe_2_0_0-RC1.tar.gz new file mode 100644 index 000000000..50fb33dd4 Binary files /dev/null and b/docs/src/.vuepress/public/download/dsf_bpe_2_0_0-RC1.tar.gz differ diff --git a/docs/src/.vuepress/public/download/dsf_fhir_2_0_0-RC1.tar.gz b/docs/src/.vuepress/public/download/dsf_fhir_2_0_0-RC1.tar.gz new file mode 100644 index 000000000..65cd6277d Binary files /dev/null and b/docs/src/.vuepress/public/download/dsf_fhir_2_0_0-RC1.tar.gz differ diff --git a/docs/src/.vuepress/sidebar/operations-v1.ts b/docs/src/.vuepress/sidebar/operations-v1.ts index 87d7936ce..c4d7d2914 100644 --- a/docs/src/.vuepress/sidebar/operations-v1.ts +++ b/docs/src/.vuepress/sidebar/operations-v1.ts @@ -1,3 +1,76 @@ +export function generate_v2_latest_sidebar() { + return [ + + { + text: "Get Started", + icon: "tool", + link: "./", + }, + "release-notes", "install", "upgrade-from-1", "allowList-mgm", "root-certificates", "passwords-secrets", { + text: "FHIR Reverse Proxy", + icon: "module", + children: [ + { + icon: "config", + text: "Configuration", + link: "fhir-reverse-proxy/configuration", + } + ]}, + { + text: "FHIR Server", + icon: "module", + prefix: "fhir/", + link: "fhir/", + children: [{ + icon: "config", + text: "Configuration", + link: "configuration" + }, { + icon: "config", + text: "Access Control", + link: "access-control" + }, { + icon: "config", + text: "OpenID Connect", + link: "oidc" + }] + }, { + text: "BPE Reverse Proxy", + icon: "module", + children: [ + { + icon: "config", + text: "Configuration", + link: "bpe-reverse-proxy/configuration", + } + ] + }, { + text: "BPE Server", + icon: "module", + prefix: "bpe/", + link: "bpe/", + children: [{ + icon: "config", + text: "Configuration", + link: "configuration" + }, { + icon: "config", + text: "Access Control", + link: "access-control" + }, { + icon: "config", + text: "OpenID Connect", + link: "oidc" + }] + }, + { + text: "Install Plugins", + icon: "plugin", + link: "install-plugins" + }] +} + + export function generate_v1_latest_sidebar() { return [ diff --git a/docs/src/.vuepress/theme.ts b/docs/src/.vuepress/theme.ts index 350a88595..e71c06b29 100644 --- a/docs/src/.vuepress/theme.ts +++ b/docs/src/.vuepress/theme.ts @@ -1,6 +1,6 @@ import { slimsearchPlugin } from "@vuepress/plugin-slimsearch"; import { hopeTheme } from "vuepress-theme-hope"; -import { generate_v1_latest_sidebar, generate_v1_gt_eq_1_7_0_sidebar, generate_v1_gt_eq_1_5_0_sidebar, generate_v1_gt_eq_1_0_0_sidebar } from "./sidebar/operations-v1"; +import { generate_v1_latest_sidebar, generate_v1_gt_eq_1_7_0_sidebar, generate_v1_gt_eq_1_5_0_sidebar, generate_v1_gt_eq_1_0_0_sidebar, generate_v2_latest_sidebar } from "./sidebar/operations-v1"; export default hopeTheme({ author: { @@ -114,8 +114,7 @@ export default hopeTheme({ "/operations/old-versions": [], "/operations/latest/": generate_v1_latest_sidebar(), "/operations/next/": [], - "/operations/v2.0.0-M4/": [], - "/operations/v2.0.0-M3/": [], + "/operations/v2.0.0-RC1/": generate_v2_latest_sidebar(), "/operations/v1.9.0/": generate_v1_latest_sidebar(), "/operations/v1.8.0/": generate_v1_gt_eq_1_7_0_sidebar(), "/operations/v1.7.1/": generate_v1_gt_eq_1_7_0_sidebar(), diff --git a/docs/src/index.md b/docs/src/index.md index a3ad074b3..dcae313aa 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -48,7 +48,7 @@ The Data Sharing Framework is entering an exciting new phase. With the upcoming --- **DSF 2.0 Announcement** -We’re excited to announce that the next major release, DSF 2.0, is currently in development! This update brings significant improvements and new features designed to enhance performance and usability. In this article is a summary of what to expect in the upcoming release. Upcomming datails will be available under [Operations](operations/v2.0.0-M3/index.md) +We’re excited to announce that the next major release, DSF 2.0, is currently in development! This update brings significant improvements and new features designed to enhance performance and usability. In this article is a summary of what to expect in the upcoming release. Upcoming datails will be available under [Operations](operations/v2.0.0-RC1/index.md) [Read more](/posts/2025-07-28-dsfv2-announcement) --- diff --git a/docs/src/operations/v1.9.0/bpe-reverse-proxy/configuration.md b/docs/src/operations/v1.9.0/bpe-reverse-proxy/configuration.md index feffa2541..535b350ba 100644 --- a/docs/src/operations/v1.9.0/bpe-reverse-proxy/configuration.md +++ b/docs/src/operations/v1.9.0/bpe-reverse-proxy/configuration.md @@ -89,7 +89,7 @@ icon: config ### SSL_EXPECTED_CLIENT_I_DN_CN_VALUES - **Required:** No - **Description:** Expected client certificate issuer DN common-name `CN` values, must be a comma-separated list of strings in single quotation marks. If a client certificate from a not configured issuing ca common-name is used, the server answers with a `403 Forbidden` status code -- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` +- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA Client Authentication ECC', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA Client Authentication RSA', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` ### SSL_VERIFY_CLIENT diff --git a/docs/src/operations/v1.9.0/fhir-reverse-proxy/configuration.md b/docs/src/operations/v1.9.0/fhir-reverse-proxy/configuration.md index 3b93d3e90..dffdd658d 100644 --- a/docs/src/operations/v1.9.0/fhir-reverse-proxy/configuration.md +++ b/docs/src/operations/v1.9.0/fhir-reverse-proxy/configuration.md @@ -89,7 +89,7 @@ icon: config ### SSL_EXPECTED_CLIENT_I_DN_CN_VALUES - **Required:** No - **Description:** Expected client certificate issuer DN common-name `CN` values, must be a comma-separated list of strings in single quotation marks. If a client certificate from a not configured issuing ca common-name is used, the server answers with a `403 Forbidden` status code -- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` +- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA Client Authentication ECC', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA Client Authentication RSA', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` ### SSL_VERIFY_CLIENT diff --git a/docs/src/operations/v2.0.0-M3/index.md b/docs/src/operations/v2.0.0-M3/index.md deleted file mode 100644 index 50309c206..000000000 --- a/docs/src/operations/v2.0.0-M3/index.md +++ /dev/null @@ -1,8 +0,0 @@ -## DSF v2.0.0-M3 - -### DSF 2 Dependency Updates: Transitioning from Camunda 7 to Operaton -As part of the upcoming DSF 2 release, several internal dependencies will be updated. Where appropriate, some components will also be replaced with more sustainable alternatives to ensure long-term maintainability and support. - -One significant change involves the replacement of Camunda 7 Community Edition. As its support is scheduled to end in autumn 2025, DSF 2 will be delivered with an alternative BPMN engine. According to the current planning status, this will be [Operaton](https://operaton.org/), an open-source BPMN engine with an active development community. - -For users of DSF 1, a final release will be made available that includes the last supported version of Camunda 7 CE, allowing for continued use without immediate migration. diff --git a/docs/src/operations/v2.0.0-M4/index.md b/docs/src/operations/v2.0.0-M4/index.md deleted file mode 100644 index 50309c206..000000000 --- a/docs/src/operations/v2.0.0-M4/index.md +++ /dev/null @@ -1,8 +0,0 @@ -## DSF v2.0.0-M3 - -### DSF 2 Dependency Updates: Transitioning from Camunda 7 to Operaton -As part of the upcoming DSF 2 release, several internal dependencies will be updated. Where appropriate, some components will also be replaced with more sustainable alternatives to ensure long-term maintainability and support. - -One significant change involves the replacement of Camunda 7 Community Edition. As its support is scheduled to end in autumn 2025, DSF 2 will be delivered with an alternative BPMN engine. According to the current planning status, this will be [Operaton](https://operaton.org/), an open-source BPMN engine with an active development community. - -For users of DSF 1, a final release will be made available that includes the last supported version of Camunda 7 CE, allowing for continued use without immediate migration. diff --git a/docs/src/operations/v2.0.0-RC1/allowList-mgm.md b/docs/src/operations/v2.0.0-RC1/allowList-mgm.md new file mode 100644 index 000000000..f15eb7144 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/allowList-mgm.md @@ -0,0 +1,34 @@ +--- +title: Allow List Management +icon: share +--- +You can read all about the concept of Allow Lists [in our introduction](/explore/concepts/allow-list.md). + +## Overview +To simplify the DSF Allow List Management we have built a portal for administration. The portal is managed by the GECKO Institute at Heilbronn University. You as an DSF administrator can create or update your Allow List information. The information you provide on this portal will be transferred to us and will be used to built Allow List bundles that get distributed to the communication partners of the distributed processes. + +The DSF Allow List management tool uses client certificates for authentication. You can either use a personal client certificate or the client certificate from your DSF BPE, which needs to be added to your web-browsers certificate store. + + +## Prerequisites +1. Deployed DSF instance (test or production infrastructure) + 1.1 If none exists yet, read [the installation guide](install) +2. Certificate + 2.1 If none exists yet, read [the certificate requirements](install#client-server-certificates) +3. Organization identifier, shortest FQDN of your organizations website, e.g. `my-hospital.de` +4. FHIR endpoint URL, e.g. `https://dsf.my-hospital.de/fhir` +5. Contact details from a responsible person of your organization +6. Access to the E-Mail address from your organization for verification + + +## Start here +When you have fulfilled all the prerequisites, you can start managing your Allow Lists via the environment specific Allow List Management Tool: + +- [**Test** infrastructure](https://allowlist-test.gecko.hs-heilbronn.de) +- [**Production** infrastructure](https://allowlist.gecko.hs-heilbronn.de) + +We use different highlight colors for the DSF Allow List Management Tool: Green for the **Test** environment and blue for the **Production** infrastructure. To access the site, you have to authenticate yourself with a client certificate. Your web-browser will show a dialog to choose a valid certificate. + +::: tip Ideas for improvement? +Have you found an error or is something unclear to you? Then please feel free to contact us on the MII-Zulip Channel or write us at dsf-gecko@hs-heilbronn.de. Thank you very much! +::: \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/README.md b/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/README.md new file mode 100644 index 000000000..4e6a614a0 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/README.md @@ -0,0 +1,6 @@ +--- +title: BPE Reverse Proxy +icon: module +--- +## Overview +- [Configuration Parameters](configuration) diff --git a/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/configuration.md b/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/configuration.md new file mode 100644 index 000000000..ead8cf697 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe-reverse-proxy/configuration.md @@ -0,0 +1,109 @@ +--- +title: Configuration Parameters +icon: config +--- + +### APP_SERVER_IP +- **Required:** Yes +- **Description:** Hostname or IP-Address of the DSF BPE server application container, the reverse proxy target +- **Example:** `app`, `172.28.1.3` + + +### HTTPS_SERVER_NAME_PORT +- **Required:** Yes +- **Description:** FQDN of your DSF BPE server with port, typically `443` +- **Example:** `my-external.fqdn:443` + + +### PROXY_PASS_CONNECTION_TIMEOUT_HTTP +- **Required:** No +- **Description:** Connection timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a connection to be established +- **Default:** `30` seconds + + +### PROXY_PASS_CONNECTION_TIMEOUT_WS +- **Required:** No +- **Description:** Connection timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a connection to be established +- **Default:** `30` seconds + + +### PROXY_PASS_TIMEOUT_HTTP +- **Required:** No +- **Description:** Timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a reply +- **Default:** `60` seconds + + +### PROXY_PASS_TIMEOUT_WS +- **Required:** No +- **Description:** Timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a reply +- **Default:** `60` seconds + + +### SERVER_CONTEXT_PATH +- **Required:** No +- **Description:** Reverse proxy context path that delegates to the app server, `/` character at start, no `/` character at end, use `''` (empty string) to configure root as context path +- **Default:** `/bpe` + + +### SSL_CA_CERTIFICATE_FILE +- **Required:** No +- **Description:** Certificate chain file including all issuing, intermediate and root certificates used to validate client certificates, PEM encoded, sets the apache httpd parameter `SSLCACertificateFile`; not used by default, overrides *SSL_CA_CERTIFICATE_PATH* if not empty + + +### SSL_CA_CERTIFICATE_PATH +- **Required:** No +- **Description:** Folder with trusted full CA chains for validating client certificates +- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount +- **Default:** `ca/client_ca_chains` + + +### SSL_CA_DN_REQUEST_FILE +- **Required:** No +- **Description:** File containing all signing certificates excepted, will be used to specify the `Acceptable client certificate CA names` send to the client, during TLS handshake, sets the apache httpd parameter `SSLCADNRequestFile`; if omitted all entries from *SSL_CA_CERTIFICATE_FILE* are used; not used by default, overrides *SSL_CA_DN_REQUEST_PATH* if not empty + + +### SSL_CA_DN_REQUEST_PATH +- **Required:** No +- **Description:** Folder with trusted client certificate issuing CAs, modifies the "Acceptable client certificate CA names" send to the client, uses all from *SSL_CA_CERTIFICATE_FILE* or *SSL_CA_CERTIFICATE_PATH* if not set or empty +- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount +- **Default:** `ca/client_issuing_cas` + + +### SSL_CERTIFICATE_CHAIN_FILE +- **Required:** No +- **Description:** Certificate chain file, PEM encoded, must contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate), sets the apache httpd parameter `SSLCertificateChainFile`; can be omitted if either no chain is needed (self signed server certificate) or the file specified via *SSL_CERTIFICATE_FILE* contains the certificate chain +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_chain_file.pem` + + +### SSL_CERTIFICATE_FILE +- **Required:** Yes +- **Description:** Server certificate file, PEM encoded, sets the apache httpd parameter `SSLCertificateFile`, may contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate). Omit *SSL_CERTIFICATE_CHAIN_FILE* if chain included +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_file.pem` + + +### SSL_CERTIFICATE_KEY_FILE +- **Required:** Yes +- **Description:** Server certificate private key file, PEM encoded, unencrypted, sets the apache httpd parameter `SSLCertificateKeyFile` +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_key_file.pem` + + +### SSL_EXPECTED_CLIENT_S_DN_C_VALUES +- **Required:** No +- **Description:** Expected client certificate subject DN country `C` values, must be a comma-separated list of strings in single quotation marks, e.g. `'DE', 'FR'`. If a client certificate with a not configured subject country `C` value is used, the server answers with a `403 Forbidden` status code +- **Default:** `'DE'` + + +### SSL_EXPECTED_CLIENT_I_DN_CN_VALUES +- **Required:** No +- **Description:** Expected client certificate issuer DN common-name `CN` values, must be a comma-separated list of strings in single quotation marks. If a client certificate from a not configured issuing ca common-name is used, the server answers with a `403 Forbidden` status code +- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA Client Authentication ECC', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA Client Authentication RSA', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` + + +### SSL_VERIFY_CLIENT +- **Required:** No +- **Description:** Modifies the apache mod_ssl config parameter `SSLVerifyClient` +- **Recommendation:** Set to `optional` when using OIDC authentication +- **Default:** `require` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/bpe/README.md b/docs/src/operations/v2.0.0-RC1/bpe/README.md new file mode 100644 index 000000000..669fe4a4a --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe/README.md @@ -0,0 +1,8 @@ +--- +title: BPE Server +icon: module +--- +## Overview +- [Configuration Parameters](configuration) +- [Access Control](access-control) +- [OpenID Connect](oidc) diff --git a/docs/src/operations/v2.0.0-RC1/bpe/access-control.md b/docs/src/operations/v2.0.0-RC1/bpe/access-control.md new file mode 100644 index 000000000..e51587c62 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe/access-control.md @@ -0,0 +1,104 @@ +--- +title: Access Control +icon: config +--- + +## Overview + +The DSF BPE server provides a user interface for administrators. Without any additional configuration the user interface is not accessible with the organizations X.509 client certificate or any other certificate or OpenID Connect authenticated user. + +::: tip OpenID Connect +To enable OpenID Connect authentication of local user, see the DSF BPE server OpenID Connect [configuration page](oidc). +::: + +Access to the user interface can be enabled for client certificates and local users authenticating via OAuth 2.0 OpenID Connect. Access can be configured for so called roles, with all roles specified using the configuration parameter [DEV_DSF_BPE_SERVER_ROLECONFIG](configuration#dev-dsf-bpe-server-roleconfig). The value for this environment variable is specified as YAML using the block scalar `|`. + +The listing below shows a minimal configuration to enable access for a specific client-certificate: + +```yaml + DEV_DSF_BPE_SERVER_ROLECONFIG: | + - example_read_only_role: + thumbprint: 00474993fa261b0225f93c5a66aa6fcc... [a-f0-9]{128} + dsf-role: + - ADMIN +``` +The list of user roles above contains a single rule-entry `example_read_only_role`, matching the user via a client certificate SHA-512 thumprint and assigning three DSF roles. Any string can be used as the name for the rule-enty. + +::: tip Certificate Thumbprints +SHA-512 certificate thumbprints in HEX form `[a-f0-9]{128}` can be calculated using: +```sh +certtool --fingerprint --hash=sha512 --infile=certificate.pem +``` +::: + +Multiple user roles can be specified and all matching roles will be applied to an authenticated users. Use an empty string `""` or a single block scalar `|` character as the value for the configuration parameter [DEV_DSF_BPE_SERVER_ROLECONFIG](configuration#dev-dsf-bpe-server-roleconfig) if no roles should be configured. + +## Matching Users + +To apply roles, users can be matched via the `thumbprint`, `email`, `token-role` or `token-group` properties. A single value or a list of values can be specified. + +#### thumbprint + +The property `thumbprint` can used to specify one or multiple SHA-512 certificate thumbprints. Roles from this rule are applied to the authenticating user if the certificate matches one of the specified thumbprints. + +#### email + +Using the property `email` users can be matched against e-mail addresses specified in X.509 client certificates and in OpenID Connect access tokens. Values will be matched against e-mail addresses specified in the subject DN (via PKCS#9 extension 1.2.840.113549.1.9.1) and RFC-822 Name entries of the Subject Alternative Name field. If the user authenticates via OpenID Connect, the `email` [claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) from the access token will be matched against the property values. + +#### token-role and token-group + +With the properties `token-role` and `token-group` role and group names can be specified to match against role and group claims within OAuth 2.0 access tokens. + + +## DSF and Practitioner Roles + +Two types of roles can be applied to matched users. + +#### dsf-role + +DSF roles specified via the `dsf-role` property define general access to the user interface. Allowed values are: + +`ADMIN`. + +#### practitioner-role + +The BPE server currently does not support any practionier-roles. + + +## Examples + +The first example defines a group of DSF administrators. Two client certificates match against this role: + +```yaml + DEV_DSF_BPE_SERVER_ROLECONFIG: | + - certificate-admins: + thumbprint: + - afb68b1d9d47e691b8b3d50fd9848467cada8b1c76f5f4b45f00c9f8432d505361a3ee27805f4aa06799d9ac8dace94b3f1942fce44d84866961259b13be825d + - 2441bfddcad97eeb83c8c31fe181b90652787b8b59bf4e569219da7db4429e389479cb7c4a2f311e34217357d594ecad7d58ccfeef2a9e93c6fcf8d98897d88c + dsf-role: + - ADMIN +``` + + +The second example defines a group of DSF administrators by specifying an `admin` role that gets matched against OAuth 2.0 access tokens: + +```yaml + DEV_DSF_BPE_SERVER_ROLECONFIG: | + - token-role-admins: + token-role: admin + dsf-role: + - ADMIN +``` + + +The third example allows administrator access and users e-mail addresses to match this role. E-mail addresses from X.509 client certificates and OAuth 2.0 access tokens are matched: + +```yaml + DEV_DSF_BPE_SERVER_ROLECONFIG: | + - email-admins: + email: + - first.user@test.org + - second.user@test.org + dsf-role: + - ADMIN +``` diff --git a/docs/src/operations/v2.0.0-RC1/bpe/configuration.md b/docs/src/operations/v2.0.0-RC1/bpe/configuration.md new file mode 100644 index 000000000..56b02019c --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe/configuration.md @@ -0,0 +1,963 @@ +--- +title: Configuration Parameters +icon: config +--- + +### DEV_DSF_BPE_DB_LIQUIBASE_FORCEUNLOCK +- **Property:** dev.dsf.bpe.db.liquibase.forceUnlock +- **Required:** No +- **Description:** To force liquibase to unlock the migration lock set to `true` +- **Recommendation:** Only use this option temporarily to unlock a stuck DB migration step +- **Default:** `false` + + +### DEV_DSF_BPE_DB_LIQUIBASE_LOCKWAITTIME +- **Property:** dev.dsf.bpe.db.liquibase.lockWaitTime +- **Required:** No +- **Description:** Liquibase change lock wait time in minutes, default 2 minutes +- **Default:** `2` + + +### DEV_DSF_BPE_DB_LIQUIBASE_PASSWORD or DEV_DSF_BPE_DB_LIQUIBASE_PASSWORD_FILE +- **Property:** dev.dsf.bpe.db.liquibase.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF BPE server to execute database migrations +- **Recommendation:** Use docker secret file to configure by using *DEV_DSF_BPE_DB_LIQUIBASE_PASSWORD_FILE* +- **Example:** `/run/secrets/db_liquibase.password` + + +### DEV_DSF_BPE_DB_LIQUIBASE_USERNAME +- **Property:** dev.dsf.bpe.db.liquibase.username +- **Required:** No +- **Description:** Username to access the database from the DSF BPE server to execute database migrations +- **Default:** `liquibase_user` + + +### DEV_DSF_BPE_DB_URL +- **Property:** dev.dsf.bpe.db.url +- **Required:** Yes +- **Description:** Address of the database used for the DSF BPE server +- **Recommendation:** Change only if you don't use the provided docker-compose from the installation guide or made changes to the database settings/networking in the docker-compose +- **Example:** `jdbc:postgresql://db/bpe` + + +### DEV_DSF_BPE_DB_USER_CAMUNDA_GROUP +- **Property:** dev.dsf.bpe.db.user.camunda.group +- **Required:** No +- **Description:** Name of the user group to access the database from the DSF BPE server for camunda processes +- **Default:** `camunda_users` + + +### DEV_DSF_BPE_DB_USER_CAMUNDA_PASSWORD or DEV_DSF_BPE_DB_USER_CAMUNDA_PASSWORD_FILE +- **Property:** dev.dsf.bpe.db.user.camunda.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF BPE server for camunda processes +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_BPE_DB_USER_CAMUNDA_PASSWORD_FILE* +- **Example:** `/run/secrets/db_user_camunda.password` + + +### DEV_DSF_BPE_DB_USER_CAMUNDA_USERNAME +- **Property:** dev.dsf.bpe.db.user.camunda.username +- **Required:** No +- **Description:** Username to access the database from the DSF BPE server for camunda processes +- **Recommendation:** Use a different user then in *DEV_DSF_BPE_DB_USER_USERNAME* +- **Default:** `camunda_server_user` + + +### DEV_DSF_BPE_DB_USER_GROUP +- **Property:** dev.dsf.bpe.db.user.group +- **Required:** No +- **Description:** Name of the user group to access the database from the DSF BPE server +- **Default:** `bpe_users` + + +### DEV_DSF_BPE_DB_USER_PASSWORD or DEV_DSF_BPE_DB_USER_PASSWORD_FILE +- **Property:** dev.dsf.bpe.db.user.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF BPE server +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_BPE_DB_USER_PASSWORD_FILE* +- **Example:** `/run/secrets/db_user.password` + + +### DEV_DSF_BPE_DB_USER_USERNAME +- **Property:** dev.dsf.bpe.db.user.username +- **Required:** No +- **Description:** Username to access the database from the DSF BPE server +- **Default:** `bpe_server_user` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_CURRENTUSER +- **Property:** dev.dsf.bpe.debug.log.message.currentUser +- **Required:** No +- **Description:** To enable logging of the currently requesting user set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_DBSTATEMENT +- **Property:** dev.dsf.bpe.debug.log.message.dbStatement +- **Required:** No +- **Description:** To enable logging of DB queries set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_ONACTIVITYEND +- **Property:** dev.dsf.bpe.debug.log.message.onActivityEnd +- **Required:** No +- **Description:** To enable debug log messages for every bpmn activity end, set to `true` +- **Recommendation:** This debug function should only be activated during process plugin development +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_ONACTIVITYSTART +- **Property:** dev.dsf.bpe.debug.log.message.onActivityStart +- **Required:** No +- **Description:** To enable debug log messages for every bpmn activity start, set to `true` +- **Recommendation:** This debug function should only be activated during process plugin development +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_VARIABLES +- **Property:** dev.dsf.bpe.debug.log.message.variables +- **Required:** No +- **Description:** To enable logging of bpmn variables for every bpmn activity start or end, when logging of these events is enabled, set to `true` +- **Recommendation:** This debug function should only be activated during process plugin development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_VARIABLESLOCAL +- **Property:** dev.dsf.bpe.debug.log.message.variablesLocal +- **Required:** No +- **Description:** To enable logging of local bpmn variables for every bpmn activity start or end, when logging of these events is enabled, set to `true` +- **Recommendation:** This debug function should only be activated during process plugin development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_BPE_DEBUG_LOG_MESSAGE_WEBSERVICEREQUEST +- **Property:** dev.dsf.bpe.debug.log.message.webserviceRequest +- **Required:** No +- **Description:** To enable logging of webservices requests set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE +- **Property:** dev.dsf.bpe.fhir.client.certificate +- **Required:** Yes +- **Description:** PEM encoded file with local client certificate for https connections to local and remote DSF FHIR servers +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/app_client_certificate.pem` + + +### DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY +- **Property:** dev.dsf.bpe.fhir.client.certificate.private.key +- **Required:** Yes +- **Description:** Private key corresponding to the local client certificate as PEM encoded file. Use DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD* or *DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* if private key is encrypted +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/app_client_certificate_private_key.pem` + + +### DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD or DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.bpe.fhir.client.certificate.private.key.password +- **Required:** No +- **Description:** Password to decrypt the local client certificate encrypted private key +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* +- **Example:** `/run/secrets/app_client_certificate_private_key.pem.password` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG +- **Property:** dev.dsf.bpe.fhir.client.connections.config +- **Required:** No +- **Description:** FHIR server connections YAML config for v2 process plugins + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_ENABLE_DEBUG_LOGGING +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.enable.debug.logging +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `enable-debug-logging` and `oidc-auth.enable-debug-logging` +- **Recommendation:** To enable debug logging of requests and responses to configured FHIR servers by default set to `true` +- **Default:** `false` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_ENABLE_DEBUG_LOGGING +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.enable.debug.logging +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `oidc-auth.verify-authorized-party` +- **Recommendation:** To disable verification of the authorized party (aud) claim by default set to `false` +- **Default:** `true` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_OIDC_DISCOVERY_PATH +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.oidc.discovery.path +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for property `oidc-auth.discovery-path` +- **Default:** `/.well-known/openid-configuration` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_TEST_CONNECTION_ON_STARTUP +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.test.connection.on.startup +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `test-connection-on-startup` and `oidc-auth.test-connection-on-startup` +- **Recommendation:** To perform connection tests on BPE startup to configured FHIR servers by default set to `true` +- **Default:** `false` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_TIMEOUT_CONNECT +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.timeout.connect +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `connect-timeout` and `oidc-auth.connect-timeout` +- **Default:** `PT2S` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_TIMEOUT_READ +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.timeout.read +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `read-timeout` and `oidc-auth.read-timeout` +- **Default:** `PT10M` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.bpe.fhir.client.connections.config.default.trust.server.certificate.cas +- **Required:** No +- **Description:** FHIR server connections YAML: Default value for properties `trusted-root-certificates-file` and `oidc-auth.trusted-root-certificates-file`. Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates. +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/app_client_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_OIDC_CACHE +- **Property:** dev.dsf.bpe.fhir.client.connections.config.oidc.cache +- **Required:** No +- **Description:** Set `false` to disable caching of OIDC discovery and jwks resources as well as access tokens in the 'Client Credentials Grant' client; access tokens are evicted 10 seconds before they expire +- **Default:** `true` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_OIDC_CACHE_TIMEOUT_ACCESS_TOKEN +- **Property:** dev.dsf.bpe.fhir.client.connections.config.oidc.cache.timeout.access.token +- **Required:** No +- **Description:** OIDC 'Client Credentials Grant' client cache timeout of access tokens before they expire, duration is subtracted from the expires at value of the access token +- **Default:** `PT10S` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_OIDC_CACHE_TIMEOUT_CONFIGURATION_RESOURCE +- **Property:** dev.dsf.bpe.fhir.client.connections.config.oidc.cache.timeout.configuration.resource +- **Required:** No +- **Description:** OIDC 'Client Credentials Grant' client cache timeout of the 'openid-configuration' discovery resource +- **Default:** `PT1H` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_OIDC_CACHE_TIMEOUT_JWKS_RESOURCE +- **Property:** dev.dsf.bpe.fhir.client.connections.config.oidc.cache.timeout.jwks.resource +- **Required:** No +- **Description:** OIDC 'Client Credentials Grant' client cache timeout of the jwks resource +- **Default:** `PT1H` + + +### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_OIDC_TIME_VALIDATION_LEEWAY +- **Property:** dev.dsf.bpe.fhir.client.connections.config.oidc.time.validation.leeway +- **Required:** No +- **Description:** OIDC 'Client Credentials Grant' client access token time validation leeway for 'Not Before', 'Issued At' and 'Expires At' values +- **Default:** `PT10S` + + +### DEV_DSF_BPE_FHIR_CLIENT_LOCAL_TIMEOUT_CONNECT +- **Property:** dev.dsf.bpe.fhir.client.local.timeout.connect +- **Required:** No +- **Description:** Timeout until a connection is established with the local DSF FHIR server +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT2S` + + +### DEV_DSF_BPE_FHIR_CLIENT_LOCAL_TIMEOUT_READ +- **Property:** dev.dsf.bpe.fhir.client.local.timeout.read +- **Required:** No +- **Description:** Timeout until reading a resource from the local DSF FHIR server is aborted +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT60S` + + +### DEV_DSF_BPE_FHIR_CLIENT_LOCAL_VERBOSE +- **Property:** dev.dsf.bpe.fhir.client.local.verbose +- **Required:** No +- **Description:** To enable verbose logging of requests to and replies from the local DSF FHIR server, set to `true` +- **Default:** `false` + + +### DEV_DSF_BPE_FHIR_CLIENT_REMOTE_TIMEOUT_CONNECT +- **Property:** dev.dsf.bpe.fhir.client.remote.timeout.connect +- **Required:** No +- **Description:** Timeout until a connection is established with a remote DSF FHIR server +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT5S` + + +### DEV_DSF_BPE_FHIR_CLIENT_REMOTE_TIMEOUT_READ +- **Property:** dev.dsf.bpe.fhir.client.remote.timeout.read +- **Required:** No +- **Description:** Timeout until a reading a resource from a remote DSF FHIR server is aborted +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT60S` + + +### DEV_DSF_BPE_FHIR_CLIENT_REMOTE_VERBOSE +- **Property:** dev.dsf.bpe.fhir.client.remote.verbose +- **Required:** No +- **Description:** To enable verbose logging of requests to and replies from remote DSF FHIR servers, set to `true` +- **Default:** `false` + + +### DEV_DSF_BPE_FHIR_CLIENT_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.bpe.fhir.client.trust.server.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates to validate server certificates for https connections to local and remote DSF FHIR servers +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/app_client_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_BPE_FHIR_QUESTIONNAIRE_RESPONSE_SUBSCRIPTION_SEARCH_PARAMETER +- **Property:** dev.dsf.bpe.fhir.questionnaire.response.subscription.search.parameter +- **Required:** No +- **Description:** Subscription to receive notifications about questionnaire response resources from the DSF FHIR server +- **Default:** `?criteria:exact=QuestionnaireResponse%3Fstatus%3Dcompleted&status=active&type=websocket&payload=application/fhir%2Bjson` + + +### DEV_DSF_BPE_FHIR_SERVER_BASE_URL +- **Property:** dev.dsf.bpe.fhir.server.base.url +- **Required:** Yes +- **Description:** Base address of the local DSF FHIR server to read/store fhir resources +- **Example:** `https://foo.bar/fhir` + + +### DEV_DSF_BPE_FHIR_TASK_SUBSCRIPTION_RETRY_MAX +- **Property:** dev.dsf.bpe.fhir.task.subscription.retry.max +- **Required:** No +- **Description:** Number of retries until a websocket connection can be established with the DSF FHIR server, `-1` means infinite number of retries +- **Default:** `-1` + + +### DEV_DSF_BPE_FHIR_TASK_SUBSCRIPTION_RETRY_SLEEP +- **Property:** dev.dsf.bpe.fhir.task.subscription.retry.sleep +- **Required:** No +- **Description:** Time between two retries to establish a websocket connection with the DSF FHIR server +- **Default:** `PT5S` + + +### DEV_DSF_BPE_FHIR_TASK_SUBSCRIPTION_SEARCH_PARAMETER +- **Property:** dev.dsf.bpe.fhir.task.subscription.search.parameter +- **Required:** No +- **Description:** Subscription to receive notifications about task resources from the DSF FHIR server +- **Default:** `?criteria:exact=Task%3Fstatus%3Drequested&status=active&type=websocket&payload=application/fhir%2Bjson` + + +### DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE +- **Property:** dev.dsf.bpe.mail.client.certificate +- **Required:** No +- **Description:** PEM encoded file with client certificate used to authenticate against the SMTP server. Requires SMTP over TLS to be enabled via *DEV_DSF_BPE_MAIL_USESMTPS* +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/smtp_server_client_certificate.pem` + + +### DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY +- **Property:** dev.dsf.bpe.mail.client.certificate.private.key +- **Required:** No +- **Description:** Private key corresponging to the SMTP server client certificate as PEM encoded file. Use DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD* or *DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* if private key is encrypted. Requires SMTP over TLS to be enabled via *DEV_DSF_BPE_MAIL_USESMTPS* +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/smtp_server_client_certificate_private_key.pem` + + +### DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD or DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.bpe.mail.client.certificate.private.key.password +- **Required:** No +- **Description:** Password to decrypt the local client certificate encrypted private key +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_BPE_MAIL_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* +- **Example:** `/run/secrets/smtp_server_client_certificate_private_key.pem.password` + + +### DEV_DSF_BPE_MAIL_FROMADDRESS +- **Property:** dev.dsf.bpe.mail.fromAddress +- **Required:** No +- **Description:** Mail service sender address +- **Example:** `sender@localhost` + + +### DEV_DSF_BPE_MAIL_HOST +- **Property:** dev.dsf.bpe.mail.host +- **Required:** No +- **Description:** SMTP server hostname +- **Example:** `smtp.server.de` + + +### DEV_DSF_BPE_MAIL_MAILONERRORLOGEVENTBUFFERSIZE +- **Property:** dev.dsf.bpe.mail.mailOnErrorLogEventBufferSize +- **Required:** No +- **Description:** Number of previous INFO, WARN log messages to include in ERROR log event mails (>=0); requires send mail on ERROR log event option to be enabled to have an effect +- **Default:** `4` + + +### DEV_DSF_BPE_MAIL_MAILONERRORLOGEVENTDEBUGLOGLOCATION +- **Property:** dev.dsf.bpe.mail.mailOnErrorLogEventDebugLogLocation +- **Required:** No +- **Description:** Location of the BPE debug log as displayed in the footer of ERROR log event mails, does not modify the actual location of the debug log file; requires send mail on ERROR log event option to be enabled to have an effect +- **Default:** `/opt/bpe/log/bpe.log` + + +### DEV_DSF_BPE_MAIL_PASSWORD or DEV_DSF_BPE_MAIL_PASSWORD_FILE +- **Property:** dev.dsf.bpe.mail.password +- **Required:** No +- **Description:** SMTP server authentication password +- **Recommendation:** Configure if the SMTP server requires username/password authentication; use docker secret file to configure using *DEV_DSF_BPE_MAIL_PASSWORD_FILE*; enable SMTP over TLS via *DEV_DSF_BPE_MAIL_USESMTPS* + + +### DEV_DSF_BPE_MAIL_PORT +- **Property:** dev.dsf.bpe.mail.port +- **Required:** No +- **Description:** SMTP server port +- **Example:** `465` +- **Default:** `0` + + +### DEV_DSF_BPE_MAIL_REPLYTOADDRESSES +- **Property:** dev.dsf.bpe.mail.replyToAddresses +- **Required:** No +- **Description:** Mail service reply to addresses; comma or space separated list, YAML block scalars supported +- **Example:** `reply.to@localhost` + + +### DEV_DSF_BPE_MAIL_SENDMAILONERRORLOGEVENT +- **Property:** dev.dsf.bpe.mail.sendMailOnErrorLogEvent +- **Required:** No +- **Description:** To enable mails being send for every ERROR logged, set to `true`; requires SMTP server to be configured +- **Default:** `false` + + +### DEV_DSF_BPE_MAIL_SENDTESTMAILONSTARTUP +- **Property:** dev.dsf.bpe.mail.sendTestMailOnStartup +- **Required:** No +- **Description:** To enable a test mail being send on startup of the BPE, set to `true`; requires SMTP server to be configured +- **Default:** `false` + + +### DEV_DSF_BPE_MAIL_SMIME_P12KEYSTORE +- **Property:** dev.dsf.bpe.mail.smime.p12Keystore +- **Required:** No +- **Description:** PKCS12 encoded file with S/MIME certificate, private key and certificate chain to enable send mails to be S/MIME signed +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/smime_certificate.p12` + + +### DEV_DSF_BPE_MAIL_SMIME_P12KEYSTORE_PASSWORD or DEV_DSF_BPE_MAIL_SMIME_P12KEYSTORE_PASSWORD_FILE +- **Property:** dev.dsf.bpe.mail.smime.p12Keystore.password +- **Required:** No +- **Description:** Password to decrypt the PKCS12 encoded S/MIMIE certificate file +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_BPE_MAIL_SMIME_P12KEYSTORE_PASSWORD_FILE* +- **Example:** `/run/secrets/smime_certificate.p12.password` + + +### DEV_DSF_BPE_MAIL_TOADDRESSES +- **Property:** dev.dsf.bpe.mail.toAddresses +- **Required:** No +- **Description:** Mail service recipient addresses, configure at least one; comma or space separated list, YAML block scalars supported +- **Example:** `recipient@localhost` + + +### DEV_DSF_BPE_MAIL_TOADDRESSESCC +- **Property:** dev.dsf.bpe.mail.toAddressesCc +- **Required:** No +- **Description:** Mail service CC recipient addresses; comma or space separated list, YAML block scalars supported +- **Example:** `cc.recipient@localhost` + + +### DEV_DSF_BPE_MAIL_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.bpe.mail.trust.server.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates to validate the server certificate of the SMTP server. Requires SMTP over TLS to be enabled via *DEV_DSF_BPE_MAIL_USESMTPS* +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/smtp_server_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_BPE_MAIL_USERNAME +- **Property:** dev.dsf.bpe.mail.username +- **Required:** No +- **Description:** SMTP server authentication username +- **Recommendation:** Configure if the SMTP server requires username/password authentication; enable SMTP over TLS via *DEV_DSF_BPE_MAIL_USESMTPS* + + +### DEV_DSF_BPE_MAIL_USESMTPS +- **Property:** dev.dsf.bpe.mail.useSmtps +- **Required:** No +- **Description:** To enable SMTP over TLS (smtps), set to `true` +- **Default:** `false` + + +### DEV_DSF_BPE_PROCESS_API_ALLOWED_BPE_CLASSES +- **Property:** dev.dsf.bpe.process.api.allowed.bpe.classes +- **Required:** No +- **Description:** Map with files containing qualified class names allowed to be loaded by plugins for api versions; map key must match v([1-9]+[0-9]*) +- **Recommendation:** Change only during development +- **Example:** `{v1: 'some/example.file', v2: 'other.file'}` +- **Default:** `{:}` + + +### DEV_DSF_BPE_PROCESS_API_ALLOWED_BPE_RESOURCE +- **Property:** dev.dsf.bpe.process.api.allowed.bpe.resource +- **Required:** No +- **Description:** Map with files containing resources allowed to be loaded by plugins for api versions; map key must match v([1-9]+[0-9]*) +- **Recommendation:** Change only during development +- **Example:** `{v1: 'some/example.file', v2: 'other.file'}` +- **Default:** `{:}` + + +### DEV_DSF_BPE_PROCESS_API_DIRECTORY +- **Property:** dev.dsf.bpe.process.api.directory +- **Required:** No +- **Description:** Directory containing the DSF BPE process plugin api jar files +- **Recommendation:** Change only during development +- **Default:** `api` + + +### DEV_DSF_BPE_PROCESS_API_RESOURCES_WITH_PRIORITY +- **Property:** dev.dsf.bpe.process.api.resources.with.priority +- **Required:** No +- **Description:** Map with files containing api/plugin resource with priority over bpe resources for plugins for api versions; map key must match v([1-9]+[0-9]*) +- **Recommendation:** Change only during development +- **Example:** `{v1: 'some/example.file', v2: 'other.file'}` +- **Default:** `{:}` + + +### DEV_DSF_BPE_PROCESS_ENGINE_COREPOOLSIZE +- **Property:** dev.dsf.bpe.process.engine.corePoolSize +- **Required:** No +- **Description:** Process engine job executor core pool size +- **Default:** `4` + + +### DEV_DSF_BPE_PROCESS_ENGINE_MAXPOOLSIZE +- **Property:** dev.dsf.bpe.process.engine.maxPoolSize +- **Required:** No +- **Description:** Process engine job executor max pool size, additional threads until max pool size are created if the queue is full +- **Default:** `10` + + +### DEV_DSF_BPE_PROCESS_ENGINE_QUEUESIZE +- **Property:** dev.dsf.bpe.process.engine.queueSize +- **Required:** No +- **Description:** Process engine job executor queue size, jobs are added to the queue if all core pool threads are busy +- **Default:** `40` + + +### DEV_DSF_BPE_PROCESS_EXCLUDED +- **Property:** dev.dsf.bpe.process.excluded +- **Required:** No +- **Description:** List of process names that should be excluded from deployment during startup of the DSF BPE server; comma or space separated list, YAML block scalars supported +- **Recommendation:** Only deploy processes that can be started depending on your organization's roles in the Allow-List +- **Example:** `dsfdev_updateAllowList|1.0, another_process|x.y` + + +### DEV_DSF_BPE_PROCESS_FHIR_SERVER_RETRY_MAX +- **Property:** dev.dsf.bpe.process.fhir.server.retry.max +- **Required:** No +- **Description:** Number of retries until a connection can be established with the local DSF FHIR server during process deployment, `-1` means infinite number of retries +- **Default:** `-1` + + +### DEV_DSF_BPE_PROCESS_FHIR_SERVER_RETRY_SLEEP +- **Property:** dev.dsf.bpe.process.fhir.server.retry.sleep +- **Required:** No +- **Description:** Time between two retries to establish a connection with the local DSF FHIR server during process deployment +- **Default:** `PT5S` + + +### DEV_DSF_BPE_PROCESS_FHIR_VALIDATION_ENABLED +- **Property:** dev.dsf.bpe.process.fhir.validation.enabled +- **Required:** No +- **Description:** Set to true to enable FHIR validation feature for process plugins, not implemented for DSF version 2.0.x +- **Default:** `false` + + +### DEV_DSF_BPE_PROCESS_PLUGIN_DIRECTORY +- **Property:** dev.dsf.bpe.process.plugin.directory +- **Required:** No +- **Description:** Directory containing the DSF BPE process plugins for deployment on startup of the DSF BPE server +- **Recommendation:** Change only if you don't use the provided directory structure from the installation guide or made changes to tit +- **Default:** `process` + + +### DEV_DSF_BPE_PROCESS_PLUGIN_EXPLODED +- **Property:** dev.dsf.bpe.process.plugin.exploded +- **Required:** No +- **Description:** Directories containing exploded DSF BPE process plugins for deployment on startup of the DSF BPE server; comma or space separated list, YAML block scalars supported +- **Recommendation:** Only for testing + + +### DEV_DSF_BPE_PROCESS_RETIRED +- **Property:** dev.dsf.bpe.process.retired +- **Required:** No +- **Description:** List of already deployed process names that should be retired during startup of the DSF BPE server; comma or space separated list, YAML block scalars supported +- **Recommendation:** Retire processes that where deployed previously but are not anymore available +- **Example:** `old_process|x.y` + + +### DEV_DSF_BPE_PROCESS_THREADS +- **Property:** dev.dsf.bpe.process.threads +- **Required:** No +- **Description:** Number of parallel Task / QuestionnaireResponse threads to start new or continue existing processes, a value `<= 0` means number of cpu cores +- **Default:** `-1` + + +### DEV_DSF_BPE_SERVER_BASE_URL +- **Property:** dev.dsf.bpe.server.base.url +- **Required:** No +- **Description:** Base address of the BPE server, configure when exposing the web-ui +- **Example:** `https://foo.bar/bpe` +- **Default:** `https://localhost/bpe` + + +### DEV_DSF_BPE_SERVER_ROLECONFIG +- **Property:** dev.dsf.bpe.server.roleConfig +- **Required:** No +- **Description:** Role config YAML as defined in [FHIR Server: Access Control](access-control) + + +### DEV_DSF_BPE_SERVER_STATIC_RESOURCE_CACHE +- **Property:** dev.dsf.bpe.server.static.resource.cache +- **Required:** No +- **Description:** To disable static resource caching, set to `false` +- **Recommendation:** Only set to `false` for development +- **Default:** `true` + + +### DEV_DSF_BPE_SERVER_UI_THEME +- **Property:** dev.dsf.bpe.server.ui.theme +- **Required:** No +- **Description:** UI theme parameter, adds a color indicator to the ui to distinguish `dev`, `test` and `prod` environments if configured; supported values: `dev`, `test` and `prod` + + +### DEV_DSF_LOG_CONFIG +- **Property:** dev.dsf.log.config +- **Required:** No +- **Description:** Location of a log4j configuration xml file; if file is readable, overrides configuration specified via *DEV_DSF_LOG_...* parameters +- **Default:** `conf/log4j2.xml` + + +### DEV_DSF_LOG_CONSOLE_ERR_ENABLED +- **Property:** dev.dsf.log.console.err.enabled +- **Required:** No +- **Description:** Set to `true` to enable console err output of the standard logger +- **Default:** `false` + + +### DEV_DSF_LOG_CONSOLE_ERR_LEVEL +- **Property:** dev.dsf.log.console.err.level +- **Required:** No +- **Description:** Standard logger console err output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `INFO` + + +### DEV_DSF_LOG_CONSOLE_ERR_STYLE +- **Property:** dev.dsf.log.console.err.style +- **Required:** No +- **Description:** Standard logger console err output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT`, `TEXT_COLOR_MDC`, `TEXT_COLOR` +- **Default:** `TEXT_COLOR` + + +### DEV_DSF_LOG_CONSOLE_OUT_ENABLED +- **Property:** dev.dsf.log.console.out.enabled +- **Required:** No +- **Description:** Set to `false` to disable console out output of the standard logger +- **Default:** `true` + + +### DEV_DSF_LOG_CONSOLE_OUT_LEVEL +- **Property:** dev.dsf.log.console.out.level +- **Required:** No +- **Description:** Standard logger console out output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `INFO` + + +### DEV_DSF_LOG_CONSOLE_OUT_STYLE +- **Property:** dev.dsf.log.console.out.style +- **Required:** No +- **Description:** Standard logger console out output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT`, `TEXT_COLOR_MDC`, `TEXT_COLOR` +- **Default:** `TEXT_COLOR` + + +### DEV_DSF_LOG_DATA_CONSOLE_ERR_ENABLED +- **Property:** dev.dsf.log.data.console.err.enabled +- **Required:** No +- **Description:** Set to `true` to enable console err output of the special data logger; the data logger can be used by process plugins to log sensitive data +- **Default:** `false` + + +### DEV_DSF_LOG_DATA_CONSOLE_ERR_STYLE +- **Property:** dev.dsf.log.data.console.err.style +- **Required:** No +- **Description:** Special data logger console err style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT` + + +### DEV_DSF_LOG_DATA_CONSOLE_OUT_ENABLED +- **Property:** dev.dsf.log.data.console.out.enabled +- **Required:** No +- **Description:** Set to `true` to enable console out output of the special data logger; the data logger can be used by process plugins to log sensitive data +- **Default:** `false` + + +### DEV_DSF_LOG_DATA_CONSOLE_OUT_STYLE +- **Property:** dev.dsf.log.data.console.out.style +- **Required:** No +- **Description:** Special data logger console out style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT` + + +### DEV_DSF_LOG_DATA_FILE_ENABLED +- **Property:** dev.dsf.log.data.file.enabled +- **Required:** No +- **Description:** Set to `true` to enable log file output of the special data logger; the data logger can be used by process plugins to log sensitive data +- **Default:** `false` + + +### DEV_DSF_LOG_DATA_FILE_STYLE +- **Property:** dev.dsf.log.data.file.style +- **Required:** No +- **Description:** Special data logger file style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT` + + +### DEV_DSF_LOG_FILE_ENABLED +- **Property:** dev.dsf.log.file.enabled +- **Required:** No +- **Description:** Set to `false` to disable log file output of the standard logger +- **Default:** `true` + + +### DEV_DSF_LOG_FILE_LEVEL +- **Property:** dev.dsf.log.file.level +- **Required:** No +- **Description:** Standard logger log file output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `DEBUG` + + +### DEV_DSF_LOG_FILE_STYLE +- **Property:** dev.dsf.log.file.style +- **Required:** No +- **Description:** Standard logger log file output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT_MDC` + + +### DEV_DSF_PROXY_NOPROXY +- **Property:** dev.dsf.proxy.noProxy +- **Required:** No +- **Description:** Forward proxy no-proxy list, entries will match exactly or against (one level) sub-domains, if no port is specified - all ports are matched; comma or space separated list, YAML block scalars supported +- **Example:** `foo.bar, test.com:8080` + + +### DEV_DSF_PROXY_PASSWORD or DEV_DSF_PROXY_PASSWORD_FILE +- **Property:** dev.dsf.proxy.password +- **Required:** No +- **Description:** Forward Proxy password +- **Recommendation:** Configure password if proxy requires authentication, use docker secret file to configure using *DEV_DSF_PROXY_PASSWORD_FILE* + + +### DEV_DSF_PROXY_URL +- **Property:** dev.dsf.proxy.url +- **Required:** No +- **Description:** Forward (http/https) proxy url, use *DEV_DSF_BPE_PROXY_NOPROXY* to list domains that do not require a forward proxy +- **Example:** `http://proxy.foo:8080` + + +### DEV_DSF_PROXY_USERNAME +- **Property:** dev.dsf.proxy.username +- **Required:** No +- **Description:** Forward proxy username +- **Recommendation:** Configure username if proxy requires authentication + + +### DEV_DSF_SERVER_API_HOST +- **Property:** dev.dsf.server.api.host +- **Required:** No +- **Description:** API connector host, default in docker image: `0.0.0.0` +- **Default:** `127.0.0.1` + + +### DEV_DSF_SERVER_API_PORT +- **Property:** dev.dsf.server.api.port +- **Required:** No +- **Description:** API connector port, default in docker image: `8080` + + +### DEV_DSF_SERVER_AUTH_CLIENT_CERTIFICATE_HEADER +- **Property:** dev.dsf.server.auth.client.certificate.header +- **Required:** No +- **Description:** Name of HTTP header with client certificate from reverse proxy +- **Default:** `X-ClientCert` + + +### DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW +- **Property:** dev.dsf.server.auth.oidc.authorization.code.flow +- **Required:** No +- **Description:** Set to `true` to enable OIDC authorization code flow +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL*, *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID* and *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET* or *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT +- **Property:** dev.dsf.server.auth.oidc.back.channel.logout +- **Required:** No +- **Description:** Set to `true` to enable OIDC back-channel logout +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* to be set to `true` (enabled), *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID* and *DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH +- **Property:** dev.dsf.server.auth.oidc.back.channel.logout.path +- **Required:** No +- **Description:** Path called by the OIDC provide to request back-channel logout +- **Default:** `/back-channel-logout` + + +### DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN +- **Property:** dev.dsf.server.auth.oidc.bearer.token +- **Required:** No +- **Description:** Set to `true` to enable OIDC bearer token authentication +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN_AUDIENCE +- **Property:** dev.dsf.server.auth.oidc.bearer.token.audience +- **Required:** No +- **Description:** Audience (aud) value to verify before accepting OIDC bearer tokens, uses value from `DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID` by default, set blank string e.g. `''` to disable +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL* to be specified and *DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN* set tor `true` + + +### DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID +- **Property:** dev.dsf.server.auth.oidc.client.id +- **Required:** No +- **Description:** OIDC provider client_id, must be specified if *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* is enabled + + +### DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET or DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE +- **Property:** dev.dsf.server.auth.oidc.client.secret +- **Required:** No +- **Description:** OIDC provider client_secret, must be specified if *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* is enabled + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate +- **Required:** No +- **Description:** PEM encoded file with client certificate for https connections to the OIDC provider +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_client_certificate.pem` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate.private.key +- **Required:** No +- **Description:** Private key corresponding to the client certificate for the OIDC provider as PEM encoded file. Use *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD* or *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* if private key is encrypted +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_client_certificate_private_key.pem` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD or DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate.private.key.password +- **Required:** No +- **Description:** Password to decrypt the client certificate for the OIDC provider encrypted private key +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* +- **Example:** `/run/secrets/oidc_provider_client_certificate_private_key.pem.password` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TIMEOUT_CONNECT +- **Property:** dev.dsf.server.auth.oidc.provider.client.timeout.connect +- **Required:** No +- **Description:** OIDC provider client connect timeout +- **Default:** `PT5S` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TIMEOUT_READ +- **Property:** dev.dsf.server.auth.oidc.provider.client.timeout.read +- **Required:** No +- **Description:** OIDC provider client read timeout +- **Default:** `PT30S` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.server.auth.oidc.provider.client.trust.server.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates to validate server certificates for https connections to the OIDC provider +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_DISCOVERY_PATH +- **Property:** dev.dsf.server.auth.oidc.provider.discovery.path +- **Required:** No +- **Description:** OIDC provider discovery path +- **Default:** `/.well-known/openid-configuration` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL +- **Property:** dev.dsf.server.auth.oidc.provider.realm.base.url +- **Required:** No +- **Description:** OIDC provider realm base url +- **Example:** `https://keycloak.test.com:8443/realms/example-realm-name` + + +### DEV_DSF_SERVER_AUTH_TRUST_CLIENT_CERTIFICATE_CAS +- **Property:** dev.dsf.server.auth.trust.client.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted full CA chains to validate client certificates for https connections from local and remote clients +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/app_client_trust_certificates.pem` +- **Default:** `ca/client_ca_chains` + + +### DEV_DSF_SERVER_CERTIFICATE +- **Property:** dev.dsf.server.certificate +- **Required:** No +- **Description:** Server certificate file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_CHAIN +- **Property:** dev.dsf.server.certificate.chain +- **Required:** No +- **Description:** Server certificate chain file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_KEY +- **Property:** dev.dsf.server.certificate.key +- **Required:** No +- **Description:** Server certificate private key file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_KEY_PASSWORD or DEV_DSF_SERVER_CERTIFICATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.server.certificate.key.password +- **Required:** No +- **Description:** Server certificate private key file password for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CONTEXT_PATH +- **Property:** dev.dsf.server.context.path +- **Required:** No +- **Description:** Web application context path, default in `bpe` docker image: `/bpe`, default in `fhir` docker image: `/fhir` +- **Recommendation:** Only modify for testing + + +### DEV_DSF_SERVER_STATUS_HOST +- **Property:** dev.dsf.server.status.host +- **Required:** No +- **Description:** Status connector host +- **Default:** `127.0.0.1` + + +### DEV_DSF_SERVER_STATUS_PORT +- **Property:** dev.dsf.server.status.port +- **Required:** No +- **Description:** Status connector port, default in docker image: `10000` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/bpe/oidc.md b/docs/src/operations/v2.0.0-RC1/bpe/oidc.md new file mode 100644 index 000000000..5ba035d2c --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/bpe/oidc.md @@ -0,0 +1,56 @@ +--- +title: OpenID Connect +icon: config +--- + +## Overview +Access to the DSF BPE server user interface can be configured via [access control roles](access-control). By default users are only authenticated using X.509 client certificates, but authentication for local users via OAuth 2.0 OpenID Connect can also be enabled. + +The DSF BPE server supports [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) for the user interface. [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) is also supported. + + +::: tip BPE Reverse Proxy +The DSF BPE reverse proxy requires client certificates by default. To use OpenID Connect authentication the configuration parameter [SSL_VERIFY_CLIENT](configuration/reverseproxy.html#ssl-verify-client) needs to be set to `optional`. +::: + + +## Authorization Code Flow + +To enable authentication via OpenID Connect authorization code flow, set the configuration parameter [DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW](configuration#dev-dsf-server-auth-oidc-authorization-code-flow) to `true` and specify the following parameters: + +- [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL](configuration#dev-dsf-server-auth-oidc-provider-realm-base-url) +- [DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID](configuration#dev-dsf-server-auth-oidc-client-id) +- [DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET](configuration#dev-dsf-server-auth-oidc-client-secret) + +Optionally, back channel logout can be enabled by setting [DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT](configuration#dev-dsf-server-auth-oidc-back-channel-logout) to `true`. The DSF BPE server accepts logout tokens at [DEV_DSF_BPE_SERVER_BASE_URL](configuration#dev-dsf-bpe-server-base-url) + `/back-channel-logout`. The path can be modified via [DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH](configuration#dev-dsf-server-auth-oidc-back-channel-logout-path). + +## Additional ODIC Configuration Parameter + +A number of additional `DEV_DSF_SERVER_AUTH_OIDC ...` configuration parameter are specify on the DSF BPE server [configuration parameter page](configuration). + +For example the configuration parameter [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](configuration#dev-dsf-server-auth-oidc-provider-client-trust-server-certificate-cas) can be used to specify a PEM encoded file with trusted root certificates to be used when accessing the OpenID Connect provider. If not specify the JVM default trusted root certificates are used for this connection. + + +## Example +```yaml +services: + app: + image: ghcr.io/datasharingframework/bpe:1.5.2 + # ... + secrets: + - keycloak_root_ca.pem + # ... + environment: + # ... + DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW: 'true' + DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT: 'true' + DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN: 'true' + DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL: https://keycloak.test.org/realms/dsf + DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS: /run/secrets/keycloak_root_ca.pem + DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID: dsf-bpe + DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET: n9bCMtjugv3Y_.szktXyQ2RH5se+J%o3 + # ... +secrets: + keycloak_root_ca.pem: + file: ./secrets/keycloak_root_ca.pem +``` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/README.md b/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/README.md new file mode 100644 index 000000000..d88afe12a --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/README.md @@ -0,0 +1,6 @@ +--- +title: FHIR Reverse Proxy +icon: module +--- +## Overview +- [Configuration Parameters](configuration) diff --git a/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/configuration.md b/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/configuration.md new file mode 100644 index 000000000..5c7a1cb30 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir-reverse-proxy/configuration.md @@ -0,0 +1,116 @@ +--- +title: Configuration Parameters +icon: config +--- + +### APP_SERVER_IP +- **Required:** Yes +- **Description:** Hostname or IP-Address of the DSF FHIR server application container, the reverse proxy target +- **Example:** `app`, `172.28.1.3` + + +### HTTPS_SERVER_NAME_PORT +- **Required:** Yes +- **Description:** External FQDN of your DSF FHIR server with port, typically `443` +- **Example:** `my-external.fqdn:443` + + +### PROXY_PASS_CONNECTION_TIMEOUT_HTTP +- **Required:** No +- **Description:** Connection timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a connection to be established +- **Default:** `30` seconds + + +### PROXY_PASS_CONNECTION_TIMEOUT_WS +- **Required:** No +- **Description:** Connection timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a connection to be established +- **Default:** `30` seconds + + +### PROXY_PASS_TIMEOUT_HTTP +- **Required:** No +- **Description:** Timeout (seconds) for reverse proxy to app server http connection, time the proxy waits for a reply +- **Default:** `60` seconds + + +### PROXY_PASS_TIMEOUT_WS +- **Required:** No +- **Description:** Timeout (seconds) for reverse proxy to app server ws connection, time the proxy waits for a reply +- **Default:** `60` seconds + + +### SERVER_CONTEXT_PATH +- **Required:** No +- **Description:** Reverse proxy context path that delegates to the app server, `/` character at start, no `/` character at end, use `''` (empty string) to configure root as context path +- **Default:** `/fhir` + + +### SSL_CA_CERTIFICATE_FILE +- **Required:** No +- **Description:** Certificate chain file including all issuing, intermediate and root certificates used to validate client certificates, PEM encoded, sets the apache httpd parameter `SSLCACertificateFile`; not used by default, overrides *SSL_CA_CERTIFICATE_PATH* if not empty + + +### SSL_CA_CERTIFICATE_PATH +- **Required:** No +- **Description:** Folder with trusted full CA chains for validating client certificates +- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount +- **Default:** `ca/client_ca_chains` + + +### SSL_CA_DN_REQUEST_FILE +- **Required:** No +- **Description:** File containing all signing certificates excepted, will be used to specify the `Acceptable client certificate CA names` send to the client, during TLS handshake, sets the apache httpd parameter `SSLCADNRequestFile`; if omitted all entries from *SSL_CA_CERTIFICATE_FILE* are used; not used by default, overrides *SSL_CA_DN_REQUEST_PATH* if not empty + + +### SSL_CA_DN_REQUEST_PATH +- **Required:** No +- **Description:** Folder with trusted client certificate issuing CAs, modifies the "Acceptable client certificate CA names" send to the client, uses all from *SSL_CA_CERTIFICATE_FILE* or *SSL_CA_CERTIFICATE_PATH* if not set or empty +- **Recommendation:** Override default folder content via bind mount or add *.crt files to default folder via bind mount +- **Default:** `ca/client_issuing_cas` + + +### SSL_CERTIFICATE_CHAIN_FILE +- **Required:** No +- **Description:** Certificate chain file, PEM encoded, must contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate), sets the apache httpd parameter `SSLCertificateChainFile`; can be omitted if either no chain is needed (self signed server certificate) or the file specified via *SSL_CERTIFICATE_FILE* contains the certificate chain +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_chain_file.pem` + + +### SSL_CERTIFICATE_CHAIN_FILE +- **Required:** No +- **Description:** Certificate chain file, PEM encoded, must contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate), sets the apache httpd parameter `SSLCertificateChainFile`; can be omitted if either no chain is needed (self signed server certificate) or the file specified via *SSL_CERTIFICATE_FILE* contains the certificate chain +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_chain_file.pem` + + +### SSL_CERTIFICATE_FILE +- **Required:** Yes +- **Description:** Server certificate file, PEM encoded, sets the apache httpd parameter `SSLCertificateFile`, may contain all certificates between the server certificate and the root ca certificate (excluding the root ca certificate). Omit *SSL_CERTIFICATE_CHAIN_FILE* if chain included +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_file.pem` + + +### SSL_CERTIFICATE_KEY_FILE +- **Required:** Yes +- **Description:** Server certificate private key file, PEM encoded, unencrypted, sets the apache httpd parameter `SSLCertificateKeyFile` +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/ssl_certificate_key_file.pem` + + +### SSL_EXPECTED_CLIENT_S_DN_C_VALUES +- **Required:** No +- **Description:** Expected client certificate subject DN country `C` values, must be a comma-separated list of strings in single quotation marks, e.g. `'DE', 'FR'`. If a client certificate with a not configured subject country `C` value is used, the server answers with a `403 Forbidden` status code +- **Default:** `'DE'` + + +### SSL_EXPECTED_CLIENT_I_DN_CN_VALUES +- **Required:** No +- **Description:** Expected client certificate issuer DN common-name `CN` values, must be a comma-separated list of strings in single quotation marks. If a client certificate from a not configured issuing ca common-name is used, the server answers with a `403 Forbidden` status code +- **Default:** `'GEANT TLS ECC 1', 'HARICA OV TLS ECC', 'GEANT TLS RSA 1', 'HARICA OV TLS RSA', 'GEANT S/MIME ECC 1', 'HARICA Client Authentication ECC', 'HARICA S/MIME ECC', 'GEANT S/MIME RSA 1', 'HARICA Client Authentication RSA', 'HARICA S/MIME RSA', 'DFN-Verein Global Issuing CA', 'Fraunhofer User CA - G02', 'D-TRUST SSL Class 3 CA 1 2009', 'Sectigo RSA Organization Validation Secure Server CA', 'GEANT OV RSA CA 4', 'GEANT Personal CA 4', 'GEANT eScience Personal CA 4', 'Sectigo ECC Organization Validation Secure Server CA', 'GEANT OV ECC CA 4', 'GEANT Personal ECC CA 4', 'GEANT eScience Personal ECC CA 4', 'D-TRUST Limited Basic CA 1-2 2019', 'D-TRUST Limited Basic CA 1-3 2019'` + + +### SSL_VERIFY_CLIENT +- **Required:** No +- **Description:** Modifies the apache mod_ssl config parameter `SSLVerifyClient` +- **Recommendation:** Set to `optional` when using OIDC authentication +- **Default:** `require` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/fhir/README.md b/docs/src/operations/v2.0.0-RC1/fhir/README.md new file mode 100644 index 000000000..cedc99c38 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir/README.md @@ -0,0 +1,8 @@ +--- +title: FHIR Server +icon: module +--- +## Overview +- [Configuration Parameters](configuration) +- [Access Control](access-control) +- [OpenID Connect](oidc) diff --git a/docs/src/operations/v2.0.0-RC1/fhir/access-control.md b/docs/src/operations/v2.0.0-RC1/fhir/access-control.md new file mode 100644 index 000000000..00a4c89f1 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir/access-control.md @@ -0,0 +1,129 @@ +--- +title: Access Control +icon: config +--- + +## Overview + +The DSF FHIR server implements a subset of the FHIR R4 [REST API](http://hl7.org/fhir/R4/http.html). When accessing the API with a web browser a limited graphical user interface is shown. Without any additional configuration the API and user interface is only accessible with the X.509 client certificate configured for the organization via the configuration parameter: [DEV_DSF_FHIR_SERVER_ORGANIZATION_THUMBPRINT](configuration#dev-dsf-fhir-server-organization-thumbprint) + +::: tip OpenID Connect +To enable OpenID Connect authentication of local user, see the DSF FHIR server OpenID Connect [configuration page](oidc). +::: + +Access to the API and user interface can be enabled for additional client certificates and local users authenticating via OAuth 2.0 OpenID Connect. Access can be configured for so called roles, with all roles specified using the configuration parameter [DEV_DSF_FHIR_SERVER_ROLECONFIG](configuration#dev-dsf-fhir-server-roleconfig). The value for this environment variable is specified as YAML using the block scalar `|`. + +The listing below shows a minimal configuration to enable read access for a specific client-certificate: + +```yaml + DEV_DSF_FHIR_SERVER_ROLECONFIG: | + - example_read_only_role: + thumbprint: 00474993fa261b0225f93c5a66aa6fcc... [a-f0-9]{128} + dsf-role: + - READ + - SEARCH + - HISTORY +``` +The list of user roles above contains a single rule-entry `example_read_only_role`, matching the user via a client certificate SHA-512 thumbprint and assigning three DSF roles. Any string can be used as the name for the rule-enty. + +::: tip Certificate Thumbprints +SHA-512 certificate thumbprints in HEX form `[a-f0-9]{128}` can be calculated using: +```sh +certtool --fingerprint --hash=sha512 --infile=certificate.pem +``` +::: + +Multiple user roles can be specified and all matching roles will be applied to an authenticated users. Use an empty string `""` or a single block scalar `|` character as the value for the configuration parameter [DEV_DSF_FHIR_SERVER_ROLECONFIG](configuration#dev-dsf-fhir-server-roleconfig) if no roles should be configured. + +## Matching Users + +To apply roles, users can be matched via the `thumbprint`, `email`, `token-role` or `token-group` properties. A single value or a list of values can be specified. + +#### thumbprint + +The property `thumbprint` can used to specify one or multiple SHA-512 certificate thumbprints. Roles from this rule are applied to the authenticating user if the certificate matches one of the specified thumbprints. + +#### email + +Using the property `email` users can be matched against e-mail addresses specified in X.509 client certificates and in OpenID Connect access tokens. Values will be matched against e-mail addresses specified in the subject DN (via PKCS#9 extension 1.2.840.113549.1.9.1) and RFC-822 Name entries of the Subject Alternative Name field. If the user authenticates via OpenID Connect, the `email` [claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) from the access token will be matched against the property values. + +#### token-role and token-group + +With the properties `token-role` and `token-group` role and group names can be specified to match against role and group claims within OAuth 2.0 access tokens. + + +## DSF and Practitioner Roles + +Two types of roles can be applied to matched users. + +#### dsf-role + +DSF roles specified via the `dsf-role` property define general access to the REST API and user interface. Allowed values are: + +`CREATE`, `READ`, `UPDATE`, `DELETE`, `SEARCH`, `HISTORY`, `PERMANENT_DELETE` and `WEBSOCKET`. + +#### practitioner-role + +In order to allow users to start processes, the property `practitioner-role` can be used to assign codes from FHIR [CodeSystem](http://hl7.org/fhir/R4/codesystem.html) resources. Codes are specified in the form `system-url|code`. +If the uses has a code specified here that match with a `requester` extension within the process plugin's [ActivityDefinition](http://hl7.org/fhir/R4/activitydefinition.html) resource, the user can start the process if he also has the `dsf-role` `CREATE`. + +Process plugins can defined and use there own code-systems. However, the DSF specifies a standard set of practitioner roles within the CodeSystem `http://dsf.dev/fhir/CodeSystem/practitioner-role`: + +`UAC_USER`, `COS_USER`, `CRR_USER`, `DIC_USER`, `DMS_USER`, `DTS_USER`, `HRP_USER`, `TTP_USER`, `AMS_USER` and `DSF_ADMIN`. + + +## Examples + +The first example defines a group of DSF administrators. Two client certificates match against this role: + +```yaml + DEV_DSF_FHIR_SERVER_ROLECONFIG: | + - certificate-admins: + thumbprint: + - afb68b1d9d47e691b8b3d50fd9848467cada8b1c76f5f4b45f00c9f8432d505361a3ee27805f4aa06799d9ac8dace94b3f1942fce44d84866961259b13be825d + - 2441bfddcad97eeb83c8c31fe181b90652787b8b59bf4e569219da7db4429e389479cb7c4a2f311e34217357d594ecad7d58ccfeef2a9e93c6fcf8d98897d88c + dsf-role: + - CREATE + - READ + - UPDATE + - DELETE + - SEARCH + - HISTORY + practitioner-role: + - http://dsf.dev/fhir/CodeSystem/practitioner-role|DSF_ADMIN + +``` + + +The second example defines a group of DSF administrators by specifying an `admin` role that gets matched against OAuth 2.0 access tokens: + +```yaml + DEV_DSF_FHIR_SERVER_ROLECONFIG: | + - token-role-admins: + token-role: admin + dsf-role: + - CREATE + - READ + - UPDATE + - DELETE + - SEARCH + - HISTORY + practitioner-role: + - http://dsf.dev/fhir/CodeSystem/practitioner-role|DSF_ADMIN + +``` + + +The third example allows read-only access. Two e-mail addresses are used to match this role. E-mail addresses from X.509 client certificates and OAuth 2.0 access tokens are matched: + +```yaml + DEV_DSF_FHIR_SERVER_ROLECONFIG: | + - read-only: + email: + - first.user@test.org + - second.user@test.org + dsf-role: + - READ + - SEARCH + - HISTORY +``` diff --git a/docs/src/operations/v2.0.0-RC1/fhir/configuration.md b/docs/src/operations/v2.0.0-RC1/fhir/configuration.md new file mode 100644 index 000000000..4c0760acb --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir/configuration.md @@ -0,0 +1,551 @@ +--- +title: Configuration Parameters +icon: config +--- + +### DEV_DSF_FHIR_CLIENT_CERTIFICATE +- **Property:** dev.dsf.fhir.client.certificate +- **Required:** Yes +- **Description:** PEM encoded file with local client certificate for https connections to remote DSF FHIR servers +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/app_client_certificate.pem` + + +### DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY +- **Property:** dev.dsf.fhir.client.certificate.private.key +- **Required:** Yes +- **Description:** Private key corresponding to the local client certificate as PEM encoded file. Use *DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD* or *DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* if private key is encrypted +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/app_client_certificate_private_key.pem` + + +### DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD or DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.fhir.client.certificate.private.key.password +- **Required:** No +- **Description:** Password to decrypt the local client certificate encrypted private key +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* +- **Example:** `/run/secrets/app_client_certificate_private_key.pem.password` + + +### DEV_DSF_FHIR_CLIENT_TIMEOUT_CONNECT +- **Property:** dev.dsf.fhir.client.timeout.connect +- **Required:** No +- **Description:** Timeout until a connection is established between this DSF FHIR server and a remote DSF FHIR server +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT2S` + + +### DEV_DSF_FHIR_CLIENT_TIMEOUT_READ +- **Property:** dev.dsf.fhir.client.timeout.read +- **Required:** No +- **Description:** Timeout until a reading a resource from a remote DSF FHIR server is aborted +- **Recommendation:** Change default value only if timeout exceptions occur +- **Default:** `PT10S` + + +### DEV_DSF_FHIR_CLIENT_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.fhir.client.trust.server.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates to validate server certificates for https connections to remote DSF FHIR servers +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/app_client_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_FHIR_CLIENT_VERBOSE +- **Property:** dev.dsf.fhir.client.verbose +- **Required:** No +- **Description:** To enable verbose logging of requests to and replies from remote DSF FHIR servers, set to `true` +- **Default:** `false` + + +### DEV_DSF_FHIR_DB_LIQUIBASE_FORCEUNLOCK +- **Property:** dev.dsf.fhir.db.liquibase.forceUnlock +- **Required:** No +- **Description:** To force liquibase to unlock the migration lock set to `true` +- **Recommendation:** Only use this option temporarily to unlock a stuck DB migration step +- **Default:** `false` + + +### DEV_DSF_FHIR_DB_LIQUIBASE_LOCKWAITTIME +- **Property:** dev.dsf.fhir.db.liquibase.lockWaitTime +- **Required:** No +- **Description:** Liquibase change lock wait time in minutes, default 2 minutes +- **Default:** `2` + + +### DEV_DSF_FHIR_DB_LIQUIBASE_PASSWORD or DEV_DSF_FHIR_DB_LIQUIBASE_PASSWORD_FILE +- **Property:** dev.dsf.fhir.db.liquibase.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF FHIR server to execute database migrations +- **Recommendation:** Use docker secret file to configure by using *DEV_DSF_FHIR_DB_LIQUIBASE_PASSWORD_FILE* +- **Example:** `/run/secrets/db_liquibase.password` + + +### DEV_DSF_FHIR_DB_LIQUIBASE_USERNAME +- **Property:** dev.dsf.fhir.db.liquibase.username +- **Required:** No +- **Description:** Username to access the database from the DSF FHIR server to execute database migrations +- **Default:** `liquibase_user` + + +### DEV_DSF_FHIR_DB_URL +- **Property:** dev.dsf.fhir.db.url +- **Required:** Yes +- **Description:** Address of the database used for the DSF FHIR server +- **Recommendation:** Change only if you don't use the provided docker-compose from the installation guide or made changes to the database settings/networking in the docker-compose +- **Example:** `jdbc:postgresql://db/fhir` + + +### DEV_DSF_FHIR_DB_USER_GROUP +- **Property:** dev.dsf.fhir.db.user.group +- **Required:** No +- **Description:** Name of the user group to access the database from the DSF FHIR server +- **Default:** `fhir_users` + + +### DEV_DSF_FHIR_DB_USER_PASSWORD or DEV_DSF_FHIR_DB_USER_PASSWORD_FILE +- **Property:** dev.dsf.fhir.db.user.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF FHIR server +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_FHIR_DB_USER_PASSWORD_FILE* +- **Example:** `/run/secrets/db_user.password` + + +### DEV_DSF_FHIR_DB_USER_PERMANENT_DELETE_GROUP +- **Property:** dev.dsf.fhir.db.user.permanent.delete.group +- **Required:** No +- **Description:** Name of the user group to access the database from the DSF FHIR server for permanent deletes +- **Default:** `fhir_permanent_delete_users` + + +### DEV_DSF_FHIR_DB_USER_PERMANENT_DELETE_PASSWORD or DEV_DSF_FHIR_DB_USER_PERMANENT_DELETE_PASSWORD_FILE +- **Property:** dev.dsf.fhir.db.user.permanent.delete.password +- **Required:** Yes +- **Description:** Password to access the database from the DSF FHIR server for permanent deletes +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_FHIR_DB_USER_PERMANENT_DELETE_PASSWORD_FILE* +- **Example:** `/run/secrets/db_user_permanent_delete.password` + + +### DEV_DSF_FHIR_DB_USER_PERMANENT_DELETE_USERNAME +- **Property:** dev.dsf.fhir.db.user.permanent.delete.username +- **Required:** No +- **Description:** Username to access the database from the DSF FHIR server for permanent deletes +- **Recommendation:** Use a different user then *DEV_DSF_FHIR_DB_USER_USERNAME* +- **Default:** `fhir_server_permanent_delete_user` + + +### DEV_DSF_FHIR_DB_USER_USERNAME +- **Property:** dev.dsf.fhir.db.user.username +- **Required:** No +- **Description:** Username to access the database from the DSF FHIR server +- **Default:** `fhir_server_user` + + +### DEV_DSF_FHIR_DEBUG_LOG_MESSAGE_CURRENTUSER +- **Property:** dev.dsf.fhir.debug.log.message.currentUser +- **Required:** No +- **Description:** To enable logging of the currently requesting user set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_FHIR_DEBUG_LOG_MESSAGE_DBSTATEMENT +- **Property:** dev.dsf.fhir.debug.log.message.dbStatement +- **Required:** No +- **Description:** To enable logging of DB queries set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_FHIR_DEBUG_LOG_MESSAGE_WEBSERVICEREQUEST +- **Property:** dev.dsf.fhir.debug.log.message.webserviceRequest +- **Required:** No +- **Description:** To enable logging of webservices requests set to `true` +- **Recommendation:** This debug function should only be activated during development; WARNING: Confidential information may be leaked via the debug log! +- **Default:** `false` + + +### DEV_DSF_FHIR_SERVER_BASE_URL +- **Property:** dev.dsf.fhir.server.base.url +- **Required:** Yes +- **Description:** Base address of this DSF FHIR server to read/store fhir resources +- **Example:** `https://foo.bar/fhir` + + +### DEV_DSF_FHIR_SERVER_INIT_BUNDLE +- **Property:** dev.dsf.fhir.server.init.bundle +- **Required:** No +- **Description:** Fhir bundle containing the initial Allow-List, loaded on startup of the DSF FHIR server +- **Recommendation:** Change only if you don't use the provided files from the installation guide, have local changes in the Allow-List or received an Allow-List from another source +- **Default:** `conf/bundle.xml` + + +### DEV_DSF_FHIR_SERVER_ORGANIZATION_IDENTIFIER_VALUE +- **Property:** dev.dsf.fhir.server.organization.identifier.value +- **Required:** Yes +- **Description:** Local identifier value used in the Allow-List +- **Recommendation:** By convention: The shortest possible FQDN that resolve the homepage of the organization +- **Example:** `hospital.com` + + +### DEV_DSF_FHIR_SERVER_ORGANIZATION_THUMBPRINT +- **Property:** dev.dsf.fhir.server.organization.thumbprint +- **Required:** No +- **Description:** The SHA-512 thumbprint of the local organization client certificate; will be calculated on startup based on the client certificate specified via *DEV_DSF_FHIR_CLIENT_CERTIFICATE* +- **Recommendation:** Do not specify this variable when using the same client certificate for the FHIR and BPE server; the thumbprint can be calculated via `certtool --fingerprint --hash=sha512 --infile=client_certificate.pem` + + +### DEV_DSF_FHIR_SERVER_PAGE_COUNT +- **Property:** dev.dsf.fhir.server.page.count +- **Required:** No +- **Description:** Page size returned by the DSF FHIR server when reading/searching fhir resources +- **Default:** `20` + + +### DEV_DSF_FHIR_SERVER_ROLECONFIG +- **Property:** dev.dsf.fhir.server.roleConfig +- **Required:** No +- **Description:** Role config YAML as defined in [FHIR Server: Access Control](access-control) + + +### DEV_DSF_FHIR_SERVER_STATIC_RESOURCE_CACHE +- **Property:** dev.dsf.fhir.server.static.resource.cache +- **Required:** No +- **Description:** To disable static resource caching, set to `false` +- **Recommendation:** Only set to `false` for development +- **Default:** `true` + + +### DEV_DSF_FHIR_SERVER_UI_THEME +- **Property:** dev.dsf.fhir.server.ui.theme +- **Required:** No +- **Description:** UI theme parameter, adds a color indicator to the ui to distinguish `dev`, `test` and `prod` environments if configured; supported values: `dev`, `test` and `prod` + + +### DEV_DSF_LOG_AUDIT_CONSOLE_ERR_ENABLED +- **Property:** dev.dsf.log.audit.console.err.enabled +- **Required:** No +- **Description:** Set to `true` to enable console err output of the audit logger +- **Default:** `false` + + +### DEV_DSF_LOG_AUDIT_CONSOLE_ERR_STYLE +- **Property:** dev.dsf.log.audit.console.err.style +- **Required:** No +- **Description:** Audit logger console err style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `STYLE_TEXT` + + +### DEV_DSF_LOG_AUDIT_CONSOLE_OUT_ENABLED +- **Property:** dev.dsf.log.audit.console.out.enabled +- **Required:** No +- **Description:** Set to `true` to enable console out output of the audit logger +- **Default:** `false` + + +### DEV_DSF_LOG_AUDIT_CONSOLE_OUT_STYLE +- **Property:** dev.dsf.log.audit.console.out.style +- **Required:** No +- **Description:** Audit logger console out style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `STYLE_TEXT` + + +### DEV_DSF_LOG_AUDIT_FILE_ENABLED +- **Property:** dev.dsf.log.audit.file.enabled +- **Required:** No +- **Description:** Set to `false` to disable log file output of the audit logger +- **Default:** `true` + + +### DEV_DSF_LOG_AUDIT_FILE_STYLE +- **Property:** dev.dsf.log.audit.file.style +- **Required:** No +- **Description:** Audit logger file style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT_MDC` + + +### DEV_DSF_LOG_CONFIG +- **Property:** dev.dsf.log.config +- **Required:** No +- **Description:** Location of a log4j configuration xml file; if file is readable, overrides configuration specified via *DEV_DSF_LOG_...* parameters +- **Default:** `conf/log4j2.xml` + + +### DEV_DSF_LOG_CONSOLE_ERR_ENABLED +- **Property:** dev.dsf.log.console.err.enabled +- **Required:** No +- **Description:** Set to `true` to enable console err output of the standard logger +- **Default:** `false` + + +### DEV_DSF_LOG_CONSOLE_ERR_LEVEL +- **Property:** dev.dsf.log.console.err.level +- **Required:** No +- **Description:** Standard logger console err output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `INFO` + + +### DEV_DSF_LOG_CONSOLE_ERR_STYLE +- **Property:** dev.dsf.log.console.err.style +- **Required:** No +- **Description:** Standard logger console err output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT`, `TEXT_COLOR_MDC`, `TEXT_COLOR` +- **Default:** `TEXT_COLOR` + + +### DEV_DSF_LOG_CONSOLE_OUT_ENABLED +- **Property:** dev.dsf.log.console.out.enabled +- **Required:** No +- **Description:** Set to `false` to disable console out output of the standard logger +- **Default:** `true` + + +### DEV_DSF_LOG_CONSOLE_OUT_LEVEL +- **Property:** dev.dsf.log.console.out.level +- **Required:** No +- **Description:** Standard logger console out output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `INFO` + + +### DEV_DSF_LOG_CONSOLE_OUT_STYLE +- **Property:** dev.dsf.log.console.out.style +- **Required:** No +- **Description:** Standard logger console out output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT`, `TEXT_COLOR_MDC`, `TEXT_COLOR` +- **Default:** `TEXT_COLOR` + + +### DEV_DSF_LOG_FILE_ENABLED +- **Property:** dev.dsf.log.file.enabled +- **Required:** No +- **Description:** Set to `false` to disable log file output of the standard logger +- **Default:** `true` + + +### DEV_DSF_LOG_FILE_LEVEL +- **Property:** dev.dsf.log.file.level +- **Required:** No +- **Description:** Standard logger log file output level, one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` +- **Default:** `DEBUG` + + +### DEV_DSF_LOG_FILE_STYLE +- **Property:** dev.dsf.log.file.style +- **Required:** No +- **Description:** Standard logger log file output style, one of: `JSON_ECS`, `JSON_GCP`, `JSON_GELF`, `JSON_LOGSTASH`, `TEXT_MDC`, `TEXT` +- **Default:** `TEXT_MDC` + + +### DEV_DSF_PROXY_NOPROXY +- **Property:** dev.dsf.proxy.noProxy +- **Required:** No +- **Description:** Forward proxy no-proxy list, entries will match exactly or against (one level) sub-domains, if no port is specified - all ports are matched; comma or space separated list, YAML block scalars supported +- **Example:** `foo.bar, test.com:8080` + + +### DEV_DSF_PROXY_PASSWORD or DEV_DSF_PROXY_PASSWORD_FILE +- **Property:** dev.dsf.proxy.password +- **Required:** No +- **Description:** Forward Proxy password +- **Recommendation:** Configure password if proxy requires authentication, use docker secret file to configure using *DEV_DSF_PROXY_PASSWORD_FILE* + + +### DEV_DSF_PROXY_URL +- **Property:** dev.dsf.proxy.url +- **Required:** No +- **Description:** Forward (http/https) proxy url, use *DEV_DSF_BPE_PROXY_NOPROXY* to list domains that do not require a forward proxy +- **Example:** `http://proxy.foo:8080` + + +### DEV_DSF_PROXY_USERNAME +- **Property:** dev.dsf.proxy.username +- **Required:** No +- **Description:** Forward proxy username +- **Recommendation:** Configure username if proxy requires authentication + + +### DEV_DSF_SERVER_API_HOST +- **Property:** dev.dsf.server.api.host +- **Required:** No +- **Description:** API connector host, default in docker image: `0.0.0.0` +- **Default:** `127.0.0.1` + + +### DEV_DSF_SERVER_API_PORT +- **Property:** dev.dsf.server.api.port +- **Required:** No +- **Description:** API connector port, default in docker image: `8080` + + +### DEV_DSF_SERVER_AUTH_CLIENT_CERTIFICATE_HEADER +- **Property:** dev.dsf.server.auth.client.certificate.header +- **Required:** No +- **Description:** Name of HTTP header with client certificate from reverse proxy +- **Default:** `X-ClientCert` + + +### DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW +- **Property:** dev.dsf.server.auth.oidc.authorization.code.flow +- **Required:** No +- **Description:** Set to `true` to enable OIDC authorization code flow +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL*, *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID* and *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET* or *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT +- **Property:** dev.dsf.server.auth.oidc.back.channel.logout +- **Required:** No +- **Description:** Set to `true` to enable OIDC back-channel logout +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* to be set to `true` (enabled), *DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID* and *DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH +- **Property:** dev.dsf.server.auth.oidc.back.channel.logout.path +- **Required:** No +- **Description:** Path called by the OIDC provide to request back-channel logout +- **Default:** `/back-channel-logout` + + +### DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN +- **Property:** dev.dsf.server.auth.oidc.bearer.token +- **Required:** No +- **Description:** Set to `true` to enable OIDC bearer token authentication +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL* to be specified +- **Default:** `false` + + +### DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN_AUDIENCE +- **Property:** dev.dsf.server.auth.oidc.bearer.token.audience +- **Required:** No +- **Description:** Audience (aud) value to verify before accepting OIDC bearer tokens, uses value from `DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID` by default, set blank string e.g. `''` to disable +- **Recommendation:** Requires *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL* to be specified and *DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN* set tor `true` + + +### DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID +- **Property:** dev.dsf.server.auth.oidc.client.id +- **Required:** No +- **Description:** OIDC provider client_id, must be specified if *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* is enabled + + +### DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET or DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE +- **Property:** dev.dsf.server.auth.oidc.client.secret +- **Required:** No +- **Description:** OIDC provider client_secret, must be specified if *DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW* is enabled + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate +- **Required:** No +- **Description:** PEM encoded file with client certificate for https connections to the OIDC provider +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_client_certificate.pem` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate.private.key +- **Required:** No +- **Description:** Private key corresponding to the client certificate for the OIDC provider as PEM encoded file. Use *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD* or *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* if private key is encrypted +- **Recommendation:** Use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_client_certificate_private_key.pem` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD or DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.server.auth.oidc.provider.client.certificate.private.key.password +- **Required:** No +- **Description:** Password to decrypt the client certificate for the OIDC provider encrypted private key +- **Recommendation:** Use docker secret file to configure using *DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE* +- **Example:** `/run/secrets/oidc_provider_client_certificate_private_key.pem.password` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TIMEOUT_CONNECT +- **Property:** dev.dsf.server.auth.oidc.provider.client.timeout.connect +- **Required:** No +- **Description:** OIDC provider client connect timeout +- **Default:** `PT5S` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TIMEOUT_READ +- **Property:** dev.dsf.server.auth.oidc.provider.client.timeout.read +- **Required:** No +- **Description:** OIDC provider client read timeout +- **Default:** `PT30S` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS +- **Property:** dev.dsf.server.auth.oidc.provider.client.trust.server.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted root certificates to validate server certificates for https connections to the OIDC provider +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/oidc_provider_trust_certificates.pem` +- **Default:** `ca/server_root_cas` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_DISCOVERY_PATH +- **Property:** dev.dsf.server.auth.oidc.provider.discovery.path +- **Required:** No +- **Description:** OIDC provider discovery path +- **Default:** `/.well-known/openid-configuration` + + +### DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL +- **Property:** dev.dsf.server.auth.oidc.provider.realm.base.url +- **Required:** No +- **Description:** OIDC provider realm base url +- **Example:** `https://keycloak.test.com:8443/realms/example-realm-name` + + +### DEV_DSF_SERVER_AUTH_TRUST_CLIENT_CERTIFICATE_CAS +- **Property:** dev.dsf.server.auth.trust.client.certificate.cas +- **Required:** No +- **Description:** Folder with PEM encoded files (*.crt, *.pem) or a single PEM encoded file with one or more trusted full CA chains to validate client certificates for https connections from local and remote clients +- **Recommendation:** Add file to default folder via bind mount or use docker secret file to configure +- **Example:** `/run/secrets/app_client_trust_certificates.pem` +- **Default:** `ca/client_ca_chains` + + +### DEV_DSF_SERVER_CERTIFICATE +- **Property:** dev.dsf.server.certificate +- **Required:** No +- **Description:** Server certificate file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_CHAIN +- **Property:** dev.dsf.server.certificate.chain +- **Required:** No +- **Description:** Server certificate chain file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_KEY +- **Property:** dev.dsf.server.certificate.key +- **Required:** No +- **Description:** Server certificate private key file for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CERTIFICATE_KEY_PASSWORD or DEV_DSF_SERVER_CERTIFICATE_KEY_PASSWORD_FILE +- **Property:** dev.dsf.server.certificate.key.password +- **Required:** No +- **Description:** Server certificate private key file password for testing +- **Recommendation:** Only specify For testing when terminating TLS in jetty server + + +### DEV_DSF_SERVER_CONTEXT_PATH +- **Property:** dev.dsf.server.context.path +- **Required:** No +- **Description:** Web application context path, default in `bpe` docker image: `/bpe`, default in `fhir` docker image: `/fhir` +- **Recommendation:** Only modify for testing + + +### DEV_DSF_SERVER_STATUS_HOST +- **Property:** dev.dsf.server.status.host +- **Required:** No +- **Description:** Status connector host +- **Default:** `127.0.0.1` + + +### DEV_DSF_SERVER_STATUS_PORT +- **Property:** dev.dsf.server.status.port +- **Required:** No +- **Description:** Status connector port, default in docker image: `10000` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/fhir/oidc.md b/docs/src/operations/v2.0.0-RC1/fhir/oidc.md new file mode 100644 index 000000000..97a435b38 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/fhir/oidc.md @@ -0,0 +1,63 @@ +--- +title: OpenID Connect +icon: config +--- + +## Overview +Access to the DSF FHIR server REST API and user interface can be configured via [access control roles](access-control). By default users are only authenticated using X.509 client certificates, but authentication for local users via OAuth 2.0 OpenID Connect can also be enabled. + +The DSF FHIR server supports [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) for the user interface as well as [Bearer Token Authentication](https://datatracker.ietf.org/doc/html/rfc6750) for the REST API. [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) is also supported. + + +::: tip FHIR Reverse Proxy +The DSF FHIR reverse proxy requires client certificates by default. To use OpenID Connect authentication the configuration parameter [SSL_VERIFY_CLIENT](/fhir-reverse-proxy/configuration.html#ssl-verify-client) needs to be set to `optional`. +::: + + +## Authorization Code Flow + +To enable authentication via OpenID Connect authorization code flow, set the configuration parameter [DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW](configuration#dev-dsf-server-auth-oidc-authorization-code-flow) to `true` and specify the following parameters: + +- [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL](configuration#dev-dsf-server-auth-oidc-provider-realm-base-url) +- [DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID](configuration#dev-dsf-server-auth-oidc-client-id) +- [DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET](configuration#dev-dsf-server-auth-oidc-client-secret) + +Optionally, back channel logout can be enabled by setting [DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT](configuration#dev-dsf-server-auth-oidc-back-channel-logout) to `true`. The DSF FHIR server accepts logout tokens at [DEV_DSF_FHIR_SERVER_BASE_URL](configuration#dev-dsf-fhir-server-base-url) + `/back-channel-logout`. The path can be modified via [DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT_PATH](configuration#dev-dsf-server-auth-oidc-back-channel-logout-path). + + +## Bearer Token Authentication + +To enable bearer token authentication, set the configuration parameter [DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN](configuration#dev-dsf-server-auth-oidc-bearer-token) to `true` and specify the following parameter: +- [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL](configuration#dev-dsf-server-auth-oidc-provider-realm-base-url) + + +## Additional ODIC Configuration Parameter + +A number of additional `DEV_DSF_SERVER_AUTH_OIDC ...` configuration parameter are specify on the DSF FHIR server [configuration parameter page](configuration). + +For example the configuration parameter [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](configuration#dev-dsf-server-auth-oidc-provider-client-trust-server-certificate-cas) can be used to specify a PEM encoded file with trusted root certificates to be used when accessing the OpenID Connect provider. If not specify the JVM default trusted root certificates are used for this connection. + + +## Example +```yaml +services: + app: + image: ghcr.io/datasharingframework/fhir:1.5.2 + # ... + secrets: + - keycloak_root_ca.pem + # ... + environment: + # ... + DEV_DSF_SERVER_AUTH_OIDC_AUTHORIZATION_CODE_FLOW: 'true' + DEV_DSF_SERVER_AUTH_OIDC_BACK_CHANNEL_LOGOUT: 'true' + DEV_DSF_SERVER_AUTH_OIDC_BEARER_TOKEN: 'true' + DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_REALM_BASE_URL: https://keycloak.test.org/realms/dsf + DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS: /run/secrets/keycloak_root_ca.pem + DEV_DSF_SERVER_AUTH_OIDC_CLIENT_ID: dsf-fhir + DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET: n9bCMtjugv3Y_.szktXyQ2RH5se+J%o3 + # ... +secrets: + keycloak_root_ca.pem: + file: ./secrets/keycloak_root_ca.pem +``` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/index.md b/docs/src/operations/v2.0.0-RC1/index.md new file mode 100644 index 000000000..652dd1390 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/index.md @@ -0,0 +1,31 @@ +--- +title: DSF 2.0.0-RC1 +icon: guide +--- + +Data Sharing Framework 2.x is the new upcoming release of the Data Sharing Framework. + +::: danger DSF 2.0 Release Candidate +This is a **pre-release version** of the Data Sharing Framework (DSF) 2.0. +Please **do not use this version in production environments**. + +We kindly invite **experienced DSF administrators** to test this release on their **staging or test instances** and share their feedback with us through the usual [communication channels](/community/communication#contact-the-team). + +Thank you for helping us improve the DSF! +::: + +# System Administrators + +- [Install DSF 2.0.0-RC1](install) +- [Upgrade from DSF 1.9.0](upgrade-from-1) + + +## New features +- See [Release Notes](https://github.com/datasharingframework/dsf/releases/tag/v2.0.0-RC1) + + diff --git a/docs/src/operations/v2.0.0-RC1/install-plugins.md b/docs/src/operations/v2.0.0-RC1/install-plugins.md new file mode 100644 index 000000000..ed4ff8996 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/install-plugins.md @@ -0,0 +1,56 @@ +--- +title: Install Plugins +icon: plugin +--- + +::: tip Marketplace for process plugins +To install and learn more about each Process Plugin, you can visit the Marketplace [here](https://hub.dsf.dev). +::: + + +## **Overview** +- You can find an overview of compatable process plugins below (last updated 2025-01-22). + + +| Process Plugin | released for test | released for production | +| -------------- | ----------------- | ----------------------- | +| [Ping-Pong](https://github.com/datasharingframework/dsf-process-ping-pong/releases) | [v1.0.1.0](https://github.com/datasharingframework/dsf-process-ping-pong/releases/tag/v1.0.1.0) | [v1.0.1.0](https://github.com/datasharingframework/dsf-process-ping-pong/releases/tag/v1.0.1.0) | +| [Allow-List](https://github.com/datasharingframework/dsf-process-allow-list/releases) | [v1.0.0.1](https://github.com/datasharingframework/dsf-process-allow-list/releases/tag/v1.0.0.1) | [v1.0.0.1](https://github.com/datasharingframework/dsf-process-allow-list/releases/tag/v1.0.0.1) | +| [MII Process Feasibility](https://github.com/medizininformatik-initiative/mii-process-feasibility/releases) | [v1.0.0.8](https://github.com/medizininformatik-initiative/mii-process-feasibility/releases/tag/v1.0.0.8) | [v1.0.0.8](https://github.com/medizininformatik-initiative/mii-process-feasibility/releases/tag/v1.0.0.8) | +| [MII Process Report](https://github.com/medizininformatik-initiative/mii-process-report/releases) | [v1.1.2.0](https://github.com/medizininformatik-initiative/mii-process-report/releases/tag/v1.1.2.0) | [v1.1.2.0](https://github.com/medizininformatik-initiative/mii-process-report/releases/tag/v1.1.2.0) | +| [MII Process Data Transfer](https://github.com/medizininformatik-initiative/mii-process-data-transfer/releases) | [v1.0.3.1](https://github.com/medizininformatik-initiative/mii-process-data-transfer/releases/tag/v1.0.3.1) | [v1.0.3.1](https://github.com/medizininformatik-initiative/mii-process-data-transfer/releases/tag/v1.0.3.1) | +| [MII Process Data Sharing](https://github.com/medizininformatik-initiative/mii-process-data-sharing/releases) | [v1.0.2.1](https://github.com/medizininformatik-initiative/mii-process-data-sharing/releases/tag/v1.0.2.1) | [v1.0.2.1](https://github.com/medizininformatik-initiative/mii-process-data-sharing/releases/tag/v1.0.2.1) | +| [NUM-RDP](https://github.com/num-codex/codex-processes-ap1/releases) | [v1.1.0.0](https://github.com/num-codex/codex-processes-ap1/releases/tag/v1.1.0.0) | [v1.1.0.0](https://github.com/num-codex/codex-processes-ap1/releases/tag/v1.1.0.0) | + + +- Explore and install Process Plugins in the Marketplace. Details on each plugin are available [here](https://hub.dsf.dev/). +- Deploying the process plugin to the DSF involves copy the process jar-file and configuring environment variable for the business process engine (BPE). + + +### Prerequisites +- A DSF installation of version 1.3.x or higher. An installation guide can be found [here](https://dsf.dev/operations/latest/install.html). + +### Deployment +- Add the process jar-file to the DSF BPE folder `/opt/bpe/process`: +``` +wget (your jar-file download link) +``` + +For example: +``` + wget https://github.com/medizininformatik-initiative/mii-process-data-sharing/releases/download/v1.0.0.1/mii-process-data-sharing-1.0.0.1.jar +``` + +- Make sure the process is readable by the bpe user or group, for example by executing: +``` +sudo chmod 440 (your jar-file name.jar) +sudo chown root:bpe (your jar-file name.jar) +``` +For example: +``` +sudo chmod 440 mii-process-data-sharing-1.0.0.1.jar +sudo chown root:bpe mii-process-data-sharing-1.0.0.1.jar +``` + +- Modify the process exclude config in `/opt/bpe/docker-compose.yml` +- **Reminder:** Update/verify required configurations in `docker-compose.yml` diff --git a/docs/src/operations/v2.0.0-RC1/install.md b/docs/src/operations/v2.0.0-RC1/install.md new file mode 100644 index 000000000..8ce7cd521 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/install.md @@ -0,0 +1,235 @@ +--- +title: Install DSF 2.0.0-RC1 +icon: install +--- + +::: danger DSF 2.0 Release Candidate +This is a **pre-release version** of the Data Sharing Framework (DSF) 2.0. +Please **do not use this version in production environments**. + +We kindly invite **experienced DSF administrators** to test this release on their **staging or test instances** and share their feedback with us through the usual [communication channels](/community/communication#contact-the-team). + +Thank you for helping us improve the DSF! +::: + +In the following installation manual we will show you how you can install your own DSF instance to be part of an already existing DSF network. + + +## Prerequisites +### Virtual Machines +* DSF FHIR VM: min. 4 GB RAM, 4 vCPU, 20 GB HDD +* DSF BPE VM: min. 4 GB RAM, 4 vCPU, 20 GB HDD +### Docker / Docker-Compose +Both VMs need latest docker (>= 24.0.0) and docker compose. For the latest install guide see https://docs.docker.com/engine/install. + +``` +sudo apt-get update +sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg +echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin +sudo systemctl enable docker.service +sudo systemctl enable containerd.service +``` + +The current version of docker compose is installed with the current docker version. + +### Client/Server Certificates +Two Certificates from a list of allowed certificate authorities (see [details about certificates](root-certificates.html)) are needed: +* Certificate _A_: Server Certificate - `TLS Web Server Authentication` +* Certificate _B_: Client Certificate - `TLS Web Client Authentication` + +If you use GÉANT TCS certificates, then they are configured by default with the necessary *X509v3 Extended Key Usage*s: `TLS Web Server Authentication, TLS Web Client Authentication`. + +For further details on supported Root Certificate Authorities click [here](root-certificates.html#list-of-default-trusted-certificate-authorities) + + +### Network setup / Network access + +* The DSF FHIR server needs to be accessible via the internet and able to access the internet without TLS interception. +* The BPE FHIR server should only be accessible by the internal network and able to access your DSF FHIR server via its external FQDN and the internet without TLS interception. + +Here is a quick overview of the expected network setup. + +| Source | Target | Port | Protocol | +| ----------------------------- | ----------------------------- | ---- | ---------------------- | +| DSF BPE (local) | DSF FHIR (local) | 443 | https, wss | +| DSF BPE (local) | DSF FHIR (other DSF communication partners) | 443 | https | +| DSF FHIR (local) | DSF FHIR (other DSF communication partners) | 443 | https (HTTP HEAD only) | +| DSF BPE (other DSF communication partners) | DSF FHIR (local) | 443 | https | +| DSF FHIR (other DSF communication partners) | DSF FHIR (local) | 443 | https (HTTP HEAD only) | + + Connections to services that are used by process plugins (e.g. a fTTP, a terminology server, simplifier.net or a local FHIR server) are not listed. Please refer to the respective process plugin documentation pages for more information. + + + +## Setup +### Prepare Certificates +1. Server Certificate (certificate _A_) + _This certificate will be used as the DSF FHIR servers server certificate (ssl_certificate_file.pem, ssl_certificate_key_file.pem)_ + * Store PEM encoded certificate as `ssl_certificate_file.pem` + * Store unencrypted, PEM encoded private-key as `ssl_certificate_key_file.pem` + * Store PEM encoded certificate chain (all intermediate CAs between the server and the root certificate, excluding root) as `ssl_certificate_chain_file.pem` + +1. Client Certificate (Certificate _B_) + _This certificate will be used as the DSF BPE servers client certificate (client_certificate.pem, client_certificate_private_key.pem) as well as the DSF FHIR servers client certificate (client_certificate.pem, client_certificate_private_key.pem)_ + * Store PEM encoded certificate as `client_certificate.pem` + * Store encrypted or not encrypted, PEM encoded private-key as `client_certificate_private_key.pem` + +### DSF FHIR Server +1. Add Group/User + Add group and user used by the DSF FHIR java application. Ubuntu compatible commands below: + ``` + sudo groupadd --gid 2101 fhir + sudo useradd --system --no-create-home --uid 2101 --gid 2101 fhir + ``` + +1. Download and Extract Config Files + Download and unpack the prepared DSF FHIR server config files and folder structure: + ``` + cd /opt + wget https://dsf.dev/download/dsf_fhir_2_0_0-RC1.tar.gz + sudo tar --same-owner -zxvf dsf_fhir_2_0_0-RC1.tar.gz + ``` + _The `tar` command will unpack the config files at `/opt/fhir` assuming you changed into the `/opt` directory._ + +1. Verify that the `fhir` system user or group can write into the following folder + * `/opt/fhir/log` + +1. Add certificates and keys + * Add the server certificate (certificate _A_), the corresponding private-key and the certificate chain (one file with all intermediate certificates, excluding the root CA) to **/opt/fhir/secrets/** + * ssl_certificate_file.pem (chmod: 440, chown: root:4101, 4101 is the user of the fhir proxy) + * ssl_certificate_key_file.pem (chmod: 440, chown: root:4101) + * ssl_certificate_chain_file.pem (chmod: 444, chown: root:fhir) + * Add the client certificate (Certificate _B_) and the corresponding private-key to **/opt/fhir/secrets/** + * client_certificate.pem (chmod: 440, chown: root:fhir) + * client_certificate_private_key.pem (chmod: 440, chown: root:fhir) + * If the private key is encrypted, add a password file with the password as the only content to **/opt/fhir/secrets/client_certificate_private_key.pem.password** + * If the private key is not encrypted, remove the corresponding docker secret lines from the `docker-compose.yml` file + ``` + L34: - app_client_certificate_private_key.pem.password + ... + L47: DEV_DSF_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE: /run/secrets/app_client_certificate_private_key.pem.password + ... + L109: app_client_certificate_private_key.pem.password: + L110: file: ./secrets/client_certificate_private_key.pem.password + ``` + + ::: tip How to chmod / chown + For the example *ssl_certificate_file.pem (chmod: 440, chown: root:4101)* you must: + + 1. Set the file content as requested + 2. Change the file permissions to 440 (allow read access to the owner of the file and the group the file belongs to, deny write access to everybody and deny read for other users): + `chmod 440 /opt/fhir/secrets/ssl_certificate_file.pem` + 3. Change the owner of the file to the user root and the group the file belongs to to the id 4101: + `chown fhir:docker /opt/fhir/secrets/ssl_certificate_file.pem` + + ::: + +1. Modify database passwords + * **/opt/fhir/secrets/db_liquibase.password** + * Generate a random password (min. 32 characters recommended) and replace the content of the file. + * **/opt/fhir/secrets/db_user.password** + * Generate a random password (min. 16 characters recommended) and replace the content of the file. + * **/opt/fhir/secrets/db_user_permanent_delete.password** + * Generate a random password (min. 16 characters recommended) and replace the content of the file. + +1. Modify the docker-compose.yml file and set environment variables to the appropriate values + * **services -> proxy -> environment:** + * **HTTPS_SERVER_NAME_PORT**: `dsf.todo.organization.com:443` + Set your FHIR servers external FQDN, e.g. `https://foo.bar.de` -> `foo.bar.de:443` + * For additional environment variables, see the FHIR Reverse Proxy [Configuration Parameters](fhir-reverse-proxy/configuration) page. + * **services -> app -> environment:** + * **DEV_DSF_FHIR_SERVER_ORGANIZATION_IDENTIFIER_VALUE**: `todo.organization.com` + Set your Organizations DSF identifier, aka the shortest FQDN that resolves to the main homepage of the organization, e.g. `hs-heilbronn.de` + * **DEV_DSF_FHIR_SERVER_BASE_URL**: `https://dsf.todo.organization.com/fhir` + Set your FHIR servers external FQDN, e.g. `foo.bar.de` -> `https://foo.bar.de/fhir` + * **DEV_DSF_FHIR_SERVER_ORGANIZATION_THUMBPRINT**: `f4344032fe77bffb912ff5abfd44da89fe64d355affb8d0f14c9ecb8bdbf92c7fe5f995b1ec0c453e4228b395e331052e4639044df4933d57721de508a84d26f` + Set the SHA-512 Hash (lowercase hex) of your client certificate (Certificate _B_) + Use `certtool --fingerprint --hash=sha512 --infile=client_certificate.pem` to generate the hash. + * **DEV_DSF_FHIR_SERVER_ROLECONFIG**: `|` + (Optional) You can add other client certificates (e.g. personal certificates from admins) to your DSF instance. For additional information, see the FHIR server [Access Control](fhir/access-control) page. + + * For additional environment variables, see the FHIR server [Configuration Parameters](fhir/configuration) page. + +1. Start the DSF FHIR Server + Start using: `docker compose up -d && docker compose logs -f` (Ctrl-C will close log, but not stop container) + +### DSF BPE Server +1. Add Group/User + Add group and user used by the DSF BPE java application. Ubuntu compatible commands below: + ``` + sudo groupadd --gid 2202 bpe + sudo useradd --system --no-create-home --uid 2202 --gid 2202 bpe + ``` +1. Download and Extract Config Files + Download and extract prepared DSF BPE server config files and folder structure: + ``` + cd /opt + wget https://dsf.dev/download/dsf_bpe_2_0_0-RC1.tar.gz + sudo tar --same-owner -zxvf dsf_bpe_2_0_0-RC1.tar.gz + ``` + _The `tar` command will unpack the config files at `/opt/bpe` assuming you changed into the `/opt` directory._ + +1. Verify that the `bpe` system user or group can write into the following folders + * `/opt/bpe/log` + +1. Add certificates and keys + * Add the client certificate (Certificate _B_) and the corresponding private-key to **/opt/bpe/secrets/** + * client_certificate.pem (chmod: 440 chown: root:bpe) + * client_certificate_private_key.pem (chmod: 440 chown: root:bpe) + * If the private key is encrypted, add a password file with the password as the only content to **/opt/bpe/secrets/client_certificate_private_key.pem.password** + * If the private key is not encrypted, remove the corresponding docker secret lines from the `docker-compose.yml` file + ``` + L12: - app_client_certificate_private_key.pem.password + ... + L32: DEV_DSF_BPE_FHIR_CLIENT_CERTIFICATE_PRIVATE_KEY_PASSWORD_FILE: /run/secrets/app_client_certificate_private_key.pem.password + ... + L83: app_client_certificate_private_key.pem.password: + L84: file: ./secrets/client_certificate_private_key.pem.password + ``` +1. Modify database passwords + * **/opt/bpe/secrets/db_liquibase.password** + * Generate a random password (min. 32 characters recommended) and replace the content of the file. + * **/opt/bpe/secrets/db_user.password** + * Generate a random password (min. 16 characters recommended) and replace the content of the file. + * **/opt/bpe/secrets/db_user_camunda.password** + * Generate a random password (min. 16 characters recommended) and replace the content of the file. + +1. Modify the docker-compose.yml file and set environment variables to the appropriate values + * **services -> app -> environment:** + * **DEV_DSF_BPE_FHIR_SERVER_BASE_URL**: `https://dsf.todo.organization.com/fhir` + Set your FHIR servers external FQDN, e.g. `foo.bar.de` -> `https://foo.bar.de/fhir` + + * For additional environment variables, see the BPE server [Configuration Parameters](bpe/configuration) page. + +1. Start the DSF BPE Server (without process plugins) + Start using: `docker compose up -d && docker compose logs -f` (Ctrl-C will close log, but not stop container) + +1. Verify DSF BPE Startup + * Check that the BPE was able to download new Task resources from the DSF FHIR server during startup. + * Check that the BPE was able to download a Subscription resource from the DSF FHIR server during startup. + * Check that the BPE was able to connect to the websocket endpoint of the DSF FHIR server during startup. + + If you need to debug the TLS connection to your DSF FHIR server use for example: + `docker run -it --rm alpine/openssl s_client your-fhir-server.fqdn:443` + The command above should print the server certificate of your DSF FHIR server (certificate _A_) and end with a message like `[...]tlsv13 alert certificate required[...]` + + +### Logs +By default, we will log both to the console (collected by docker) and to files in the log directory, so you can use `docker compose logs -f` in `/opt/bpe` and `/opt/fhir` to view informational, warning and error logs. If you encounter any error and the reported information is not detailled enough, you can also check the logs in the `/opt/fhir/log` and `/opt/bpe/log` directories with debugging logs. There, you will also find older log files. If you have any questions and can't resolve them by yourself please always include the latest logs from `/opt/fhir/log` and `/opt/bpe/log` in your support request. + +On a successful BPE start, you should see the following entries in your BPE log: + +``` +INFO Grizzly(1) - INFO Grizzly(1) - ClientEndpoint.onOpen(37) | Websocket open, session SOME_RANDOM_UUID1 +INFO Grizzly(1) - INFO Grizzly(1) - ClientEndpoint.onOpen(37) | Websocket open, session SOME_RANDOM_UUID2 +``` + +### On-Boarding +Please visit the on boarding website of your network for more information. + +::: tip Ideas for improvement? +Have you found an error or is something unclear to you? Then please feel free to write to us at dsf-gecko@hs-heilbronn.de. Thank you very much! +::: \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/passwords-secrets.md b/docs/src/operations/v2.0.0-RC1/passwords-secrets.md new file mode 100644 index 000000000..62bb2ef1f --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/passwords-secrets.md @@ -0,0 +1,33 @@ +--- +title: Passwords and Secrets +icon: safe +--- + +Environment variables ending in `_PASSWORD` or `_SECRET` can be configured using plain-text files. To achieve this, environment variable should be defined with `_FILE` appended to the name with the value defined as the location of the file. For all variables ending in `_PASSWORD_FILE` or `_SECRET_FILE` the DSF FHIR and DSF BPE applications will read the content of the fist line of the referenced file and dynamically define the corresponding `_PASSWORD` or `_SECRET` environment variables with the read values. + +### Example Environment Variables +- **DEV_DSF_BPE_DB_USER_PASSWORD_FILE**: If set to `/run/secrets/db_user_password`, the application will read the contents of the `/run/secrets/db_user_password` file and set the `DEV_DSF_BPE_DB_USER_PASSWORD` environment variable with the content from that file. +- **DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE**: If set to `/run/secrets/oidc_client_secret`, the application will read the contents of the referenced file and set the `DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET` environment variable accordingly. + +### Docker Secrets + +It is recommended to use [docker secrets](https://docs.docker.com/compose/how-tos/use-secrets) as files for these environment variables. Docker secrets are mounted as files in `/run/secrets/` inside the container. + +#### Example docker-compose +```yaml +services: + app: + image: ghcr.io/datasharingframework/fhir + secrets: + - db_user_password + - oidc_client_secret + environment: + DEV_DSF_BPE_DB_USER_PASSWORD_FILE: /run/secrets/db_user_password + DEV_DSF_SERVER_AUTH_OIDC_CLIENT_SECRET_FILE: /run/secrets/oidc_client_secret + +secrets: + db_user_password: + file: ./secrets/db_user.password + api_key: + file: ./secrets/oidc_client.secret +``` \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/release-notes.md b/docs/src/operations/v2.0.0-RC1/release-notes.md new file mode 100644 index 000000000..999cf7aea --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/release-notes.md @@ -0,0 +1,13 @@ +--- +title: Release Notes (v2.0.0-RC1) +icon: note +--- + +## [Release Notes for v2.0.0-RC1](https://github.com/datasharingframework/dsf/releases/tag/v2.0.0-RC1) + +::: tip Release Notes +You can access all release notes on our [GitHub](https://github.com/datasharingframework/dsf/releases). +::: + + +Release notes will be added after the release is published. \ No newline at end of file diff --git a/docs/src/operations/v2.0.0-RC1/root-certificates.md b/docs/src/operations/v2.0.0-RC1/root-certificates.md new file mode 100644 index 000000000..074dc0e4c --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/root-certificates.md @@ -0,0 +1,194 @@ +--- +title: Default Root Certificates +icon: safe +--- + +A number of trusted certificate authorities (CAs) are included in the DSF docker images [fhir_proxy](https://github.com/datasharingframework/dsf/pkgs/container/fhir_proxy), [fhir](https://github.com/datasharingframework/dsf/pkgs/container/fhir), [bpe_proxy](https://github.com/datasharingframework/dsf/pkgs/container/bpe_proxy) and [bpe](https://github.com/datasharingframework/dsf/pkgs/container/bpe) by default. Root and intermediate certificates as well as the configured usage of issuing CAs as either **server**, **client** oder **server and client** CA are listed at the end. + +:::info +Please ensure that you are using an organization-validated certificate (OV). We check for the presence of certain elements in the FHIR proxy. These are not set for domain-validated (DV) certificates. DV-validated certificates cannot be used in the standard setup. +::: + +## Extending or Replacing Trusted Certificate Authorities +X.509 certificates of default trusted CAs are stored as .pem files containing multiple certificates in the docker images and can be replaced by either using docker [bind mounts](https://docs.docker.com/engine/storage/bind-mounts) or configuring appropriate environment variables with different targets. + +### FHIR Reverse Proxy +Defaults are configured for the list of issuing, intermediate and root CAs used for validating client certificates (Apache httpd mod_ssl configuration option [SSLCACertificateFile](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcacertificatefile)) as well as the CA Certificates for defining acceptable CA names (option [SSLCADNRequestFile](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcadnrequestfile)). +Use the following environment variable to configure non default .pem files or override the existing files using docker bind mounts: +* [SSL_CA_CERTIFICATE_FILE](fhir-reverse-proxy/configuration.html#ssl-ca-certificate-file) + Default Value: [ca/client_cert_ca_chains.pem](/download/1.9.0/client_cert_ca_chains.pem) +* [SSL_CA_DN_REQUEST_FILE](fhir-reverse-proxy/configuration.html#ssl-ca-dn-request-file) + Default Value: [ca/client_cert_issuing_cas.pem](/download/1.9.0/client_cert_issuing_cas.pem) + +**Note:** Default file location are relative to the docker image work directory `/usr/local/apache2`. +**Also Note:** Using non default .pem files for the environment variables above may require also modifying the default values of the environment variables [SSL_EXPECTED_CLIENT_S_DN_C_VALUES](fhir-reverse-proxy/configuration.html#ssl-expected-client-s-dn-c-values) and [SSL_EXPECTED_CLIENT_I_DN_CN_VALUES](fhir-reverse-proxy/configuration.html#ssl-expected-client-i-dn-cn-values). + +### FHIR Server +Defaults are configured for the list of issuing, intermediate and root CAs used for validating client certificates as well as root CAs used for validating server certificates of remote DSF FHIR servers and the OIDC provider when using [OpenID Connect](fhir/oidc.html) for authenticating local users. +Use the following environment variable to configure non default .pem files or override the existing files using docker bind mounts: +* [DEV_DSF_SERVER_AUTH_TRUST_CLIENT_CERTIFICATE_CAS](fhir/configuration.html#dev-dsf-server-auth-trust-client-certificate-cas) + Default Value: [ca/client_cert_ca_chains.pem](/download/1.9.0/client_cert_ca_chains.pem) +* [DEV_DSF_FHIR_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](fhir/configuration.html#dev-dsf-fhir-client-trust-server-certificate-cas) + Default Value: [ca/server_cert_root_cas.pem](/download/1.9.0/server_cert_root_cas.pem) +* [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](fhir/configuration.html#dev-dsf-server-auth-oidc-provider-client-trust-server-certificate-cas) + Default Value: [ca/server_cert_root_cas.pem](/download/1.9.0/server_cert_root_cas.pem) + +**Note:** Default file location are relative to the docker image work directory `/opt/fhir`. + +### BPE Reverse Proxy +Defaults are configured for the list of issuing, intermediate and root CAs used for validating client certificates (Apache httpd mod_ssl configuration option [SSLCACertificateFile](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcacertificatefile)) as well as the CA Certificates for defining acceptable CA names (option [SSLCADNRequestFile](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcadnrequestfile)). +Use the following environment variable to configure non default .pem files or override the existing files using docker bind mounts: +* [SSL_CA_CERTIFICATE_FILE](bpe-reverse-proxy/configuration.html#ssl-ca-certificate-file) + Default Value: [ca/client_cert_ca_chains.pem](/download/1.9.0/client_cert_ca_chains.pem) +* [SSL_CA_DN_REQUEST_FILE](bpe-reverse-proxy/configuration.html#ssl-ca-dn-request-file) + Default Value: [ca/client_cert_issuing_cas.pem](/download/1.9.0/client_cert_issuing_cas.pem) + +**Note:** Default file location are relative to the docker image work directory `/usr/local/apache2`. +**Also Note:** Using non default .pem files for the environment variables above may require also modifying the default values of the environment variables [SSL_EXPECTED_CLIENT_S_DN_C_VALUES](bpe-reverse-proxy/configuration.html#ssl-expected-client-s-dn-c-values) and [SSL_EXPECTED_CLIENT_I_DN_CN_VALUES](bpe-reverse-proxy/configuration.html#ssl-expected-client-i-dn-cn-values). + +### BPE Server +Defaults are configured for the list of issuing, intermediate and root CAs used for validating client certificates as well as root CAs used for validating server certificates of local and remote DSF FHIR servers, the local mail server (if configured and SMTP over TLS required) and the OIDC provider when using [OpenID Connect](fhir/oidc.html) for authenticating local users. +Use the following environment variable to configure non default .pem files or override the existing files using docker bind mounts: +* [DEV_DSF_SERVER_AUTH_TRUST_CLIENT_CERTIFICATE_CAS](bpe/configuration.html#dev-dsf-server-auth-trust-client-certificate-cas) + Default Value: [ca/client_cert_ca_chains.pem](/download/1.9.0/client_cert_ca_chains.pem) +* [DEV_DSF_BPE_FHIR_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](bpe/configuration.html#dev-dsf-bpe-fhir-client-trust-server-certificate-cas) + Default Value: [ca/server_cert_root_cas.pem](/download/1.9.0/server_cert_root_cas.pem) + [DEV_DSF_BPE_MAIL_TRUST_SERVER_CERTIFICATE_CAS](bpe/configuration.html#dev-dsf-bpe-mail-trust-server-certificate-cas) + Default Value: [ca/server_cert_root_cas.pem](/download/1.9.0/server_cert_root_cas.pem) +* [DEV_DSF_SERVER_AUTH_OIDC_PROVIDER_CLIENT_TRUST_SERVER_CERTIFICATE_CAS](bpe/configuration.html#dev-dsf-server-auth-oidc-provider-client-trust-server-certificate-cas) + Default Value: [ca/server_cert_root_cas.pem](/download/1.9.0/server_cert_root_cas.pem) + +**Note:** Default file location are relative to the docker image work directory `/opt/bpe`. + +## List of Default Trusted Certificate Authorities +If not mentioned explicitly, issuing CAs listed will sign X.509 certificates with [Extended Key Usage](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) entries `TLS WWW server authentication` and `TLS WWW client authentication`. + +* Root CA: **HARICA TLS ECC Root CA 2021** + Info: https://crt.sh/?caid=202185 + X509 Certificate: https://crt.sh/?id=4147045948 + Not after: Feb 13 11:01:09 2045 GMT + * Issuing CA: **GEANT TLS ECC 1** + Info: https://crt.sh/?caid=390050 + X509 Certificate: https://crt.sh/?id=16099180990 + Not after: Dec 31 11:14:20 2039 GMT + * Issuing CA: **HARICA OV TLS ECC** + Info: https://crt.sh/?caid=207661 + X509 Certificate: https://crt.sh/?id=4442848530 + Not after: Mar 15 09:33:51 2036 GMT +* Root CA: **HARICA TLS RSA Root CA 2021** + Info: https://crt.sh/?caid=202184 + X509 Certificate: https://crt.sh/?id=4147041876 + Not after: Feb 13 10:55:37 2045 GMT + * Issuing CA: **GEANT TLS RSA 1** + Info: https://crt.sh/?caid=390054 + X509 Certificate: https://crt.sh/?id=16099180997 + Not after: Dec 31 11:14:59 2039 GMT + * Issuing CA: **HARICA OV TLS RSA** + Info: https://crt.sh/?caid=207660 + X509 Certificate: https://crt.sh/?id=4442848529 + Not after: Mar 15 09:34:16 2036 GMT +* Root CA: **HARICA Client ECC Root CA 2021** + Info: https://crt.sh/?caid=202189 + X509 Certificate: https://crt.sh/?id=4147052292 + Not after: Feb 13 11:03:33 2045 GMT + * Issuing CA: **GEANT S/MIME ECC 1** [client/smime certificates only] + Info: https://crt.sh/?caid=390048 + X509 Certificate: https://crt.sh/?id=16099180988 + Not after: Dec 31 11:11:39 2039 GMT + * Issuing CA: **HARICA S/MIME ECC** [client/smime certificates only] + Info: https://crt.sh/?caid=207659 + X509 Certificate: https://crt.sh/?id=4442848523 + Not after: Mar 15 09:36:57 2036 GMT + * Issuing CA: **HARICA Client Authentication ECC** [client certificates only] + Info: https://crt.sh/?caid=207671 + X509 Certificate: https://crt.sh/?id=4442848518 + Not after: Mar 15 09:17:38 2036 GMT +* Root CA: **HARICA Client RSA Root CA 2021** + Info: https://crt.sh/?caid=202188 + X509 Certificate: https://crt.sh/?id=4147049674 + Not after: Feb 13 10:58:45 2045 GMT + * Issuing CA: **GEANT S/MIME RSA 1** [client/smime certificates only] + Info: https://crt.sh/?caid=390049 + X509 Certificate: https://crt.sh/?id=16099180989 + Not after: Dec 31 11:13:07 2039 GMT + * Issuing CA: **HARICA S/MIME RSA** [client/smime certificates only] + Info: https://crt.sh/?caid=207658 + X509 Certificate: https://crt.sh/?id=4442848517 + Not after: Mar 15 09:37:37 2036 GMT + * Issuing CA: **HARICA Client Authentication RSA** [client certificates only] + Info: https://crt.sh/?caid=207670 + X509 Certificate: https://crt.sh/?id=4442848531 + Not after: Mar 15 09:19:36 2036 GMT +* Root CA: **T-TeleSec GlobalRoot Class 2** [will be removed in a future release, incl. derived CAs] + Info: https://crt.sh/?caid=6068 + X509 Certificate: https://crt.sh/?id=8733622 + Not after: Oct 1 23:59:59 2033 GMT + * Intermediate Root CA: **DFN-Verein Certification Authority 2** + Info: https://crt.sh/?caid=22818 + X509 Certificate: https://crt.sh/?id=23908438 + Not after: Feb 22 23:59:59 2031 GMT + * Issuing CA: **DFN-Verein Global Issuing CA** [existing, still valid client certificates, no new certificates] + Info: https://crt.sh/?caid=23770 + X509 Certificate: https://crt.sh/?id=25484751 + Not after: Feb 22 23:59:59 2031 GMT + * Issuing CA: **Fraunhofer User CA - G02** [existing, still valid client certificates, no new certificates] + Info: https://crt.sh/?caid=23772 + X509 Certificate: https://crt.sh/?id=25484789 + Not after: Feb 22 23:59:59 2031 GMT +* Root CA: **D-TRUST Root Class 3 CA 2 2009** + Info: https://crt.sh/?caid=712 + X509 Certificate: https://crt.sh/?id=133226 + Not after: Nov 5 08:35:58 2029 GMT + * Issuing CA: **D-TRUST SSL Class 3 CA 1 2009** [server certificates via TMF e.V.] + Info: https://crt.sh/?caid=713 + X509 Certificate: https://crt.sh/?id=133227 + Not after: Nov 5 08:35:58 2029 GMT +* Root CA: **USERTrust ECC Certification Authority** [will be removed in a future release, incl. derived CAs] + Info: https://crt.sh/?caid=1390 + X509 Certificate: https://crt.sh/?id=2841410 + Not after: Jan 18 23:59:59 2038 GMT + * Issuing CA: **Sectigo ECC Organization Validation Secure Server CA** + Info: https://crt.sh/?caid=105483 + X509 Certificate: https://crt.sh/?id=924467859 + Not after: Dec 31 23:59:59 2030 GMT + * Issuing CA: **GEANT OV ECC CA 4** + Info: https://crt.sh/?caid=160140 + X509 Certificate: https://crt.sh/?id=2475254970 + * Issuing CA: **GEANT Personal ECC CA 4** [client/smime certificates only] + Info: https://crt.sh/?caid=160136 + X509 Certificate: https://crt.sh/?id=2475254903 + Not after: May 1 23:59:59 2033 GMT + * Issuing CA: **GEANT eScience Personal ECC CA 4** [client/smime certificates only] + Info: https://crt.sh/?caid=160138 + X509 Certificate: https://crt.sh/?id=2475254888 + Not after: May 1 23:59:59 2033 GMT +* Root CA: **USERTrust RSA Certification Authority** [will be removed in a future release, incl. derived CAs] + Info: https://crt.sh/?caid=1167 + X509 Certificate: https://crt.sh/?id=1199354 + Not after: Jan 18 23:59:59 2038 GMT + * Issuing CA: **Sectigo RSA Organization Validation Secure Server CA** + Info: https://crt.sh/?caid=105487 + X509 Certificate: https://crt.sh/?id=924467857 + Not after: Dec 31 23:59:59 2030 GMT + * Issuing CA: **GEANT OV RSA CA 4** + Info: https://crt.sh/?caid=160137 + X509 Certificate: https://crt.sh/?id=2475254782 + Not after: May 1 23:59:59 2033 GMT + * Issuing CA: **GEANT Personal CA 4** [client/smime certificates only] + Info: https://crt.sh/?caid=160144 + X509 Certificate: https://crt.sh/?id=2475255043 + Not after: May 1 23:59:59 2033 GMT + * Issuing CA: **GEANT eScience Personal CA 4** [client/smime certificates only] + Info: https://crt.sh/?caid=160134 + X509 Certificate: https://crt.sh/?id=2475253350 + Not after: May 1 23:59:59 2033 GMT +* Root CA: **D-TRUST Limited Basic Root CA 1 2019** + X509 Certificate: https://www.d-trust.net/cgi-bin/D-TRUST_Limited_Basic_Root_CA_1_2019.crt + Not after: Jun 19 08:15:51 2034 GMT + * Issuing CA: **D-TRUST Limited Basic CA 1-2 2019** [client certificates via TMF e.V.] + X509 Certificate: https://www.d-trust.net/cgi-bin/D-TRUST_Limited_Basic_CA_1-2_2019.crt + Not after: Jun 19 08:15:51 2034 GMT + * Issuing CA: **D-TRUST Limited Basic CA 1-3 2019** [client certificates via TMF e.V.] + X509 Certificate: https://www.d-trust.net/cgi-bin/D-TRUST_Limited_Basic_CA_1-3_2019.crt + Not after: Jun 19 08:15:51 2034 GMT + diff --git a/docs/src/operations/v2.0.0-RC1/upgrade-from-1.md b/docs/src/operations/v2.0.0-RC1/upgrade-from-1.md new file mode 100644 index 000000000..b113229c9 --- /dev/null +++ b/docs/src/operations/v2.0.0-RC1/upgrade-from-1.md @@ -0,0 +1,81 @@ +--- +title: Upgrade from DSF 1.9.0 +icon: update +--- + +::: danger DSF 2.0 Release Candidate +This is a **pre-release version** of the Data Sharing Framework (DSF) 2.0. +Please **do not use this version in production environments**. + +We kindly invite **experienced DSF administrators** to test this release on their **staging or test instances** and share their feedback with us through the usual [communication channels](/community/communication#contact-the-team). + +Thank you for helping us improve the DSF! +::: + +Upgrading the DSF from 1.9.0 to 2.0.0-RC1 involves modifying the docker-compose.yml files and recreating the containers. + +::: warning Update to DSF 1.9.0 first +When upgrading from DSF version < 1.9.0 it is important to migrate to [DSF 1.9.0 first](../v1.9.0/upgrade-from-1). +::: + + +## Modify DSF FHIR Server Setup +1. Preparation / Backup + * We recommend to create a backup of the `/opt/fhir` directory before proceeding with the upgrade. + For example using: `sudo cp -rp /opt/fhir /opt/fhir_backup_pre_2.0.0-RC1_upgrade` + +2. Modify the DSF FHIR docker-compose.yml file, replace the version number with 2.0.0-RC1. +```diff + version: '3.8' + services: + proxy: +- image: ghcr.io/datasharingframework/fhir_proxy:1.9.0 ++ image: ghcr.io/datasharingframework/fhir_proxy:2.0.0-RC1 + restart: on-failure +... + app: +- image: ghcr.io/datasharingframework/fhir:1.9.0 ++ image: ghcr.io/datasharingframework/fhir:2.0.0-RC1 + restart: on-failure +... + +``` + + +3. Upgrade the DSF FHIR containers + From `/opt/fhir` execute + ``` + docker compose up -d && docker compose logs -f + ``` + +## Modify DSF BPE Server Setup +1. Preparation / Backup + * We recommend to create a backup of the `/opt/bpe` directory before proceeding with the upgrade. + For example using: `sudo cp -rp /opt/bpe /opt/bpe_backup_pre_2.0.0-RC1_upgrade` + +2. Modify the DSF BPE docker-compose.yml file, replace the version number with 2.0.0-RC1. +```diff + version: '3.8' + services: + app: +- image: ghcr.io/datasharingframework/bpe:1.9.0 ++ image: ghcr.io/datasharingframework/bpe:2.0.0-RC1 + restart: on-failure +... +``` + +3. Upgrade the DSF BPE containers + From `/opt/bpe` execute + ``` + docker compose up -d && docker compose logs -f + ``` + +5. Verify your upgrade: + * Verify the DSF FHIR server is running in version 2.0.0-RC1. The log should contain a message: + `INFO main - BuildInfoReaderImpl.logBuildInfo(137) | Artifact: dsf-fhir-server-jetty, version: 2.0.0-RC1, [...]` + * Verify the DSF FHIR server started without errors + * Verify the DSF FHIR server is accessible via https, for example by browsing to https://your-dsf-endpoint.de/fhir/ (authentication with your client-certificate) + * Verify the DSF BPE server is running in version 2.0.0-RC1. The log should contain a message: + `INFO main - BuildInfoReaderImpl.logBuildInfo(137) | Artifact: dsf-bpe-server-jetty, version: 2.0.0-RC1, [...]` + * Verify the DSF BPE server started without errors + * Verify your install with a ping/pong test diff --git a/docs/src/posts/2025-07-28-dsfv2-announcement.md b/docs/src/posts/2025-07-28-dsfv2-announcement.md index c25bc4004..6ba3669ce 100644 --- a/docs/src/posts/2025-07-28-dsfv2-announcement.md +++ b/docs/src/posts/2025-07-28-dsfv2-announcement.md @@ -32,4 +32,4 @@ Following the production release of DSF 2, further development of DSF 1 will be The new API V2 is particularly relevant for stakeholders involved in the development of custom process plugins. Feedback and contributions to the ongoing development are welcome. -Any changes to the current timeline will be communicated promptly. Upcomming datails will be available under [Operations](../operations/v2.0.0-M3/index.md). +Any changes to the current timeline will be communicated promptly. Upcomming datails will be available under [Operations](../operations/v2.0.0-RC1/index.md).