added files for DSF v1.9.0

Author: schwzr

docs/src/.vuepress/layouts/PageLayout.vue

@@ -4,7 +4,7 @@ import { useRoute, useRouter } from "vue-router";
 import { ref, onMounted } from 'vue'
 
 const version = ref("");
-const latestVersion = "v1.8.0";
+const latestVersion = "v1.9.0";
 
 
 function setVersionBasedOnCurrentPath() : void {
@@ -55,7 +55,8 @@ function navigateToNewVersion() {
       <div class="version-selector" v-if="route.path.startsWith('/operations/')">
         <label class="vp-sidebar-header" for="version-select"><strong>Version:</strong> </label>
         <select id="version-select" class="vp-sidebar-header" v-model="version" @change="navigateToNewVersion">
-        <option value="v1.8.0">latest (1.8.0)</option>
+        <option value="v1.9.0">latest (1.9.0)</option>
+        <option value="v1.8.0">1.8.0</option>
         <option value="v1.7.1">1.7.1</option>
         <option value="v1.7.0">1.7.0</option>
         <option value="v1.6.0">1.6.0</option>

docs/src/.vuepress/theme.ts

@@ -116,8 +116,9 @@ export default hopeTheme({
     "/operations/next/": [],
     "/operations/v2.0.0-M4/": [],
     "/operations/v2.0.0-M3/": [],
-    "/operations/v1.8.0/": generate_v1_latest_sidebar(),
-    "/operations/v1.7.1/": generate_v1_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(),
     "/operations/v1.7.0/": generate_v1_gt_eq_1_7_0_sidebar(),
     "/operations/v1.6.0/": generate_v1_gt_eq_1_5_0_sidebar(),
     "/operations/v1.5.2/": generate_v1_gt_eq_1_5_0_sidebar(),

docs/src/operations/latest

@@ -1 +1 @@
-v1.8.0
+v1.9.0

docs/src/operations/v1.9.0/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 <a href="https://mii.zulipchat.com/#narrow/stream/392426-Data-Sharing-Framework-.28DSF.29">MII-Zulip Channel</a> or write us at <a href="mailto:[email protected]">[email protected]</a>. Thank you very much!
+:::

docs/src/operations/v1.9.0/bpe-reverse-proxy/README.md

@@ -0,0 +1,6 @@
+---
+title: BPE Reverse Proxy
+icon: module
+---
+## Overview
+- [Configuration Parameters](configuration)

docs/src/operations/v1.9.0/bpe-reverse-proxy/configuration.md

@@ -0,0 +1,99 @@
+---
+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`
+- **Recommendation:** Use docker secret file to configure
+- **Default:** `ca/client_cert_ca_chains.pem`
+
+
+### 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
+- **Recommendation:** Use docker secret file to configure
+- **Default:** `ca/client_cert_issuing_cas.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 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'`
+
+
+### SSL_VERIFY_CLIENT
+- **Required:** No
+- **Description:** Modifies the apache mod_ssl config parameter `SSLVerifyClient`
+- **Recommendation:** Set to `optional` when using OIDC authentication
+- **Default:** `require`

docs/src/operations/v1.9.0/bpe/README.md

@@ -0,0 +1,8 @@
+---
+title: BPE Server
+icon: module
+---
+## Overview
+- [Configuration Parameters](configuration)
+- [Access Control](access-control)
+- [OpenID Connect](oidc)

docs/src/operations/v1.9.0/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:
+              - [email protected]
+              - [email protected]
+            dsf-role:
+              - ADMIN
+```