diff --git a/docs/src/.vuepress/public/schema/fhir_client_connections.json b/docs/src/.vuepress/public/schema/fhir_client_connections.json new file mode 100644 index 000000000..17981d942 --- /dev/null +++ b/docs/src/.vuepress/public/schema/fhir_client_connections.json @@ -0,0 +1,347 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "base-url": { + "title": "FHIR server base URL", + "type": "string" + }, + "connect-timeout": { + "type": "string", + "format": "duration", + "pattern": "^P(([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+(\\.?[0-9]+)?S)?))?$" + }, + "read-timeout": { + "type": "string", + "format": "duration", + "pattern": "^P(([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+(\\.?[0-9]+)?S)?))?$" + }, + "enable-debug-logging": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": ["y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off", "OFF"] + } + ] + }, + "test-connection-on-startup": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": ["y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off", "OFF"] + } + ] + }, + "trusted-root-certificates-file": { + "type": "string" + }, + "basic-auth": { + "title": "Basic authentication", + "type": "object", + "properties": { + "password": { + "type": "string" + }, + "password-file": { + "type": "string" + }, + "username": { + "type": "string" + } + }, + "required": [ + "username" + ], + "oneOf": [ + { + "required": [ + "password" + ], + "not": { + "required": [ + "password-file" + ] + } + }, + { + "required": [ + "password-file" + ], + "not": { + "required": [ + "password" + ] + } + } + ], + "additionalProperties": false + }, + "bearer-auth": { + "title": "Bearer token authentication", + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "token-file": { + "type": "string" + } + }, + "oneOf": [ + { + "required": [ + "token" + ], + "not": { + "required": [ + "token-file" + ] + } + }, + { + "required": [ + "token-file" + ], + "not": { + "required": [ + "token" + ] + } + } + ], + "additionalProperties": false + }, + "cert-auth": { + "title": "Client certificate authentication", + "type": "object", + "properties": { + "certificate-file": { + "type": "string" + }, + "p12-file": { + "type": "string" + }, + "password": { + "type": "string" + }, + "password-file": { + "type": "string" + }, + "private-key-file": { + "type": "string" + } + }, + "oneOf": [ + { + "required": [ + "certificate-file", + "private-key-file" + ], + "not": { + "required": [ + "p12-file" + ] + }, + "oneOf": [ + { + "required": [ + "password" + ], + "not": { + "required": [ + "password-file" + ] + } + }, + { + "required": [ + "password-file" + ], + "not": { + "required": [ + "password" + ] + } + }, + { + "not": { + "anyOf": [ + { + "required": [ + "password" + ] + }, + { + "required": [ + "password-file" + ] + } + ] + } + } + ] + }, + { + "required": [ + "p12-file" + ], + "not": { + "required": [ + "certificate-file", + "private-key-file" + ] + }, + "oneOf": [ + { + "required": [ + "password" + ], + "not": { + "required": [ + "password-file" + ] + } + }, + { + "required": [ + "password-file" + ], + "not": { + "required": [ + "password" + ] + } + }, + { + "not": { + "anyOf": [ + { + "required": [ + "password" + ] + }, + { + "required": [ + "password-file" + ] + } + ] + } + } + ] + } + ], + "additionalProperties": false + }, + "oidc-auth": { + "title": "OIDC client credentials flow authentication", + "type": "object", + "properties": { + "base-url": { + "type": "string" + }, + "discovery-path": { + "type": "string" + }, + "client-id": { + "type": "string" + }, + "client-secret": { + "type": "string" + }, + "client-secret-file": { + "type": "string" + }, + "required-audience": { + "type": "array", + "items": { + "type": "string" + } + }, + "verify-authorized-party": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": ["y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off", "OFF"] + } + ] + }, + "connect-timeout": { + "type": "string", + "format": "duration", + "pattern": "^P(([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+(\\.?[0-9]+)?S)?))?$" + }, + "read-timeout": { + "type": "string", + "format": "duration", + "pattern": "^P(([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T([0-9]+H)?([0-9]+M)?([0-9]+(\\.?[0-9]+)?S)?))?$" + }, + "enable-debug-logging": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": ["y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off", "OFF"] + } + ] + }, + "test-connection-on-startup": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": ["y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off", "OFF"] + } + ] + }, + "trusted-root-certificates-file": { + "type": "string" + } + }, + "required": [ + "base-url", + "client-id" + ], + "oneOf": [ + { + "required": [ + "client-secret" + ], + "not": { + "required": [ + "client-secret-file" + ] + } + }, + { + "required": [ + "client-secret-file" + ], + "not": { + "required": [ + "client-secret" + ] + } + } + ], + "additionalProperties": false + } + }, + "additionalProperties": false + } +} \ No newline at end of file diff --git a/docs/src/.vuepress/sidebar/operations-v2.ts b/docs/src/.vuepress/sidebar/operations-v2.ts index 9b7c2e24d..2b329c244 100644 --- a/docs/src/.vuepress/sidebar/operations-v2.ts +++ b/docs/src/.vuepress/sidebar/operations-v2.ts @@ -1,159 +1,161 @@ export function generate_v2_latest_sidebar() { - return [ - - { - text: "Get Started", - icon: "tool", - link: "./", - }, - "release-notes", "install", "upgrade-from-2", "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" - }, { - icon: "config", - text: "Logging", - link: "logging" - }] - }, { - 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" - }, { - icon: "config", - text: "Logging", - link: "logging" - }] - }, - { - text: "Install Plugins", - icon: "plugin", - link: "install-plugins" - }] + return [{ + text: "Get Started", + icon: "tool", + link: "./", + }, + "release-notes", "install", "upgrade-from-2", "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" + }, { + icon: "config", + text: "Logging", + link: "logging" + }] + }, { + 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" + }, { + icon: "config", + text: "Logging", + link: "logging" + }, { + icon: "config", + text: "FHIR Client Connections", + link: "fhir-client-connections" + }] + }, + { + text: "Install Plugins", + icon: "plugin", + link: "install-plugins" + }] } export function generate_v2_0_0_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" - }, { - icon: "config", - text: "Logging", - link: "logging" - }] - }, { - 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" - }, { - icon: "config", - text: "Logging", - link: "logging" - }] - }, - { - text: "Install Plugins", - icon: "plugin", - link: "install-plugins" - }] + 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" + }, { + icon: "config", + text: "Logging", + link: "logging" + }] + }, { + 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" + }, { + icon: "config", + text: "Logging", + link: "logging" + }] + }, + { + text: "Install Plugins", + icon: "plugin", + link: "install-plugins" + }] } \ No newline at end of file diff --git a/docs/src/operations/v2.0.0/bpe/configuration.md b/docs/src/operations/v2.0.0/bpe/configuration.md index ae3559ed0..aceeb51aa 100644 --- a/docs/src/operations/v2.0.0/bpe/configuration.md +++ b/docs/src/operations/v2.0.0/bpe/configuration.md @@ -171,7 +171,7 @@ icon: config - **Required:** No - **Description:** FHIR server connections YAML config for v2 process plugins - + ### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_OIDC_DISCOVERY_PATH - **Property:** dev.dsf.bpe.fhir.client.connections.config.default.oidc.discovery.path diff --git a/docs/src/operations/v2.0.1/bpe/README.md b/docs/src/operations/v2.0.1/bpe/README.md index b5441d2d9..93cd24fc6 100644 --- a/docs/src/operations/v2.0.1/bpe/README.md +++ b/docs/src/operations/v2.0.1/bpe/README.md @@ -6,4 +6,5 @@ icon: module - [Configuration Parameters](configuration) - [Access Control](access-control) - [OpenID Connect](oidc) -- [Logging](logging) \ No newline at end of file +- [Logging](logging) +- [FHIR Client Connections](fhir-client-connections) \ No newline at end of file diff --git a/docs/src/operations/v2.0.1/bpe/configuration.md b/docs/src/operations/v2.0.1/bpe/configuration.md index ae3559ed0..aceeb51aa 100644 --- a/docs/src/operations/v2.0.1/bpe/configuration.md +++ b/docs/src/operations/v2.0.1/bpe/configuration.md @@ -171,7 +171,7 @@ icon: config - **Required:** No - **Description:** FHIR server connections YAML config for v2 process plugins - + ### DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG_DEFAULT_OIDC_DISCOVERY_PATH - **Property:** dev.dsf.bpe.fhir.client.connections.config.default.oidc.discovery.path diff --git a/docs/src/operations/v2.0.1/bpe/fhir-client-connections.md b/docs/src/operations/v2.0.1/bpe/fhir-client-connections.md new file mode 100644 index 000000000..5b990daaf --- /dev/null +++ b/docs/src/operations/v2.0.1/bpe/fhir-client-connections.md @@ -0,0 +1,84 @@ +--- +title: FHIR Client Connections +icon: config +--- + +::: info Compatible Process Plugins +To our knowledge, as of January 2026 no process plugins have been released into production compatible with this plugin API v2 feature. +::: + +AS part of the process plugin API v2 the DSF BPE Server provides a standardized way for plugins to use FHIR (data) server client connections configured for the entire BPE server. Connections are configured using YAML and specified via the environment variable [`DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG`](configuration.html#dev-dsf-bpe-fhir-client-connections-config). The value for this environment variable is specified as YAML using the block scalar |. + +The listing below shows a minimal configuration: + +```yaml + DEV_DSF_BPE_FHIR_CLIENT_CONNECTIONS_CONFIG: | + min-server: + base-url: http://min.server/fhir +``` + + +The mechanism supports authenticated and non-authenticated connections to FHIR (data) servers using `http` and `https` connections. Basic, Bearer-Token, Client-Certificate, and OIDC Client-Credentials-Flow authentication schemes are supported. + +Multiple connections can be configured. Every connection has an ID (valid YAML property name) that needs to be supplied to the process plugin that is supposed to use the connection. Multiple process plugins can use the same connection config. + + + +A JSON schema is available to validate the configuration YAML: https://dsf.dev/schema/fhir_client_connections.json + +### Configuration Examples + +#### No Authentication, some defaults overridden + +ID: `no-auth-server` + +```yaml +# yaml-language-server: $schema=https://dsf.dev/schema/fhir_client_connections.json +no-auth-server: + base-url: https://no.auth.server:8443/fhir + test-connection-on-startup: yes + enable-debug-logging: yes + connect-timeout: PT0.5S + read-timeout: PT5M + trusted-root-certificates-file: 'ca.crt' +``` + +#### Basic Authentication + +ID: `basic-auth-server` + +```yaml +basic-auth-server: + base-url: https://basic.auth.server/fhir + basic-auth: + username: user + password-file: 'password.file’ +``` + +#### Client Certificate Authentication + +ID: `cert-auth-server` + +```yaml +cert-auth-server: + base-url: https://cert.auth.server/fhir/foo + cert-auth: + private-key-file: 'client.key' + certificate-file: 'client.crt' + password: 'password' +``` + +#### OIDC Client-Credentials-Flow Authentication + +ID: `oidc-auth-server` + +```yaml +oidc-auth-server: + base-url: https://oidc.auth.server/fhir + oidc-auth: + base-url: https://oidc.server + client-id: some_client_id + client-secret-file: 'path/password.file’ +``` + +For a full list of configuration properties see the FHIR client connections [validation schema](https://dsf.dev/schema/fhir_client_connections.json). \ No newline at end of file