27.1.1Gateway Setup

Setting up the Gateway involves a few key setting, described here.

27.1.2Server Configuration

The FHIR Gateway provides a FHIR REST endpoint, served as an HTTP server. This endpoint supports a set of standard endpoint configuration properties, including:

• FHIR Version (the version of FHIR that FHIR clients invoking the gateway endpoint are expected to support)

• Port (the port to listen on)

• TLS/SSL (support for the HTTPS protocol)

• Security: The endpoint can be secured with HTTP Basic and OpenID Connect / SMART, and fully supports authorization checks on the data being returned based on user permissions and approved SMART scopes

• Request Validation: The endpoint can be configured to validate requests (see Request Validating Enabled). Additionally, instance validation can be configured by setting a validation dependency to the validation-supporting module

27.1.3Encryption JWKS (Keystore)

The FHIR Gateway uses Encrypted JSON Web Tokens (JWE) to encode data about the backend servers in a way that prevents clients from learning internal implementation details. A JWKS keystore must be supplied as a part of the gateway module configuration.

Many tools exist to create JWKS files. One such tool is the mkjwk tool available at: https://mkjwk.org/

To create a JWK using this tool, the following settings are recommended:

• Type: RSA
• Key Size: 4096
• Key Use: Encryption
• Algorithm: RSA-OAEP
• Key ID: SHA-256

Click on the "generate" button and copy the Public and Private Keypair Set. This can be pasted directly into the Encryption JWKS (Text) setting, or imported by file using the Encryption JWKS (File) setting.

27.1.4Configuration Document

Details about the target servers that the gateway will communicate with are supplied in the Gateway Configuration Document.

27.1.5Interceptors

Custom interceptors may be registered in order to provide specific functionality. See Gateway Interceptor Examples for samples.

27.1.6Error Handling

The gateway server will attempt to propagate errors which are thrown by target servers back to the client. If the target server returns a non-successful statue code and includes an OperationOutcome resource, this OperationOutcome will be returned to the client.

If the request has been handled by multiple target servers, for example when the route is a parallel search route with multiple targets, the issues contained in the response OperationOutcome resources will be aggregated into a single OperationOutcome which is returned to the gateway client.

Note that this logic does not apply to authentication/authorization failures returned by the target server (HTTP 401 and 403 respectively). These will never be propagaged back to the client.