<B>Notice: Thank you for your interest in our repository. As of April 19, 2023, this repository is no longer being developed or maintained. We recommend that you use the new Azure Health Data Services Toolkit

Secure FHIR Gateway and Proxy

The Secure FHIR Gateway and Proxy is an Azure Function-based solution that:

• Acts as an intelligent and secure gateway to FHIR Servers.
• Allows multi-tenant access and purpose driven security policies for specialized access to a common FHIR Server.
• Provides a consolidated approach to pre- and post-processing of FHIR Server calls to support various access and/or result filtering actions.
• Is integrated with Azure Active Directory for authentication and to provide Role-Based Access Control (RBAC).
• Acts as a FHIR-specific reverse proxy - rewriting responses and brokering requests to FHIR Servers.

Authentication and RBAC Authorization

By default the proxy will configure and use Azure Active Directory (Azure AD) as an authentication provider. You will also need to assign users/groups and/or service principals into specific server access roles in order to access the FHIR Server via the proxy. You can also offload this responsibility to API Management.

Pre and Post Processing Support

The proxy can be configured to execute any number of logic processing modules to support a variety of pre/post conditional actions on a per-call basis. You can create custom processors by implementing the IProxyPreProcess or IProxyPostProcess interfaces in a thread safe class. The modules are executed in a chained fashion determined by configured order. Context is continually updated so the last result is passed to the next member of the processor chain - resulting in a fully processed/filtered request or post-processing result. Any configured module can stop the chain progression by issuing a do-not-continue command.

The included pre- and post-processing modules that can be configured are:

• ParticipantFilterPostProcess - This processing module will filter resources linked to a user registered in a Patient Participant Role such that only records referencing that user's Patient resource are returned. Note: this only filters patient-based linked resources. You can use this module as a basis for building your own security filtering (e.g., filtering records for a user in a Practitioner Participant Role linked to a Practitioner resource, etc.).

• PublishFHIREventPostProcess - This processing module will publish FHIR Create-Update-Delete (CUD) events for resources to a configured Event Hub. These events can be subscribed to by any number of consumers in order to trigger orchestrated workflows (e.g. CDS, Audits, Alerts, etc.).

• TransformBundlePreProcess - This processing module will transform incoming transaction bundle requests into batch bundle requests and maintain UUID associations of contained resources. This is an alternative to updating FHIR Servers unable to handle transaction based requests.

• DateSortPostProcessor - This processing module allows for a date-based sorting alternative on FHIR Servers that do not natively support _sort. The processor implements a top level _sort=date or _sort=-date parameter for supported resource queries up to a configured maximum number of rows.

• ConsentOptOutFilter - This post-processing module adds the ability to deny access to FHIR Server resources for patients who have elected to OPTOUT everyone or specific individuals and/or organizations from access to their medical data.

• EverythingPatientPreProcess - This pre-processing module implements a limited $everything at the Patient level. It returns up to 5000 related resources for the Patient.

A SamplePreProcess and SamplePostProcess are available in the project folders FHIRProxy/preprocessors and FHIRProxy/postprocessors.

See the Configuration document for full descriptions and configuration instructions.

Reverse Proxy

All FHIR Server responses are re-written to include the proxy address as the appropriate endpoint so the FHIR Server URL is never directly exposed.

Architecture Overview

Deploying your own FHIR Proxy

Please note you should deploy this proxy into a tenant where you have appropriate permissions to create and manage Application Registrations, Enterprise Applications, Permissions and Role Definition Assignments.

For detailed instructions please read this document ./scripts/Readme.md

Launch Azure Cloud Shell (Bash Environment).

Clone the repo to your Bash Shell (CLI) environment.

git clone https://github.com/microsoft/fhir-proxy 

Change working directory to the repo Scripts directory.

cd ./fhir-proxy/scripts

Make the Bash scripts used for Deployment and Setup executable.

chmod +x *.bash 

Run the deployfhirproxy.bash script and follow the prompts.

./deployfhirproxy.bash 

Run the createProxyServiceClient.bash script and follow the prompts.

./createProxyServiceClient.bash

Congratulations! You now have a Secure FHIR Proxy instance with authentication running. You can now add users/groups for authorized access (see below).

Proxy Endpoint

The new endpoint for your FHIR Server should now be: https://<secure proxy url from above>/fhir/. You can use any supported FHIR HTTP verb and any FHIR compliant request/query. For example, to see the conformance statement for the FHIR Server, use your browser and access the proxy endpoint: https://<secure proxy url from above>/fhir/metadata.

Proxy endpoints will authenticate/authorize your access to the FHIR server and will execute configured pre-processing routines, pass the modified request on to the FHIR Server via the configured service client, execute configured post-processing routines on the result, and rewrite the server response to the client. The original user principal name and tenant are passed in custom headers to the FHIR server for accurate security and compliance auditing.

Additional Documentation

Adding Users/Groups to the FHIR Server Proxy

At a minimum, users must be placed in one or more FHIR Server roles in order to access the FHIR Server via the Proxy. The FHIR Server access roles are Administrator, Resource Reader, and Resource Writer.

Adding Application Service Principals to the FHIR Server Proxy

You can create service client principals and register for Application API Access to the proxy. This is useful for using the proxy in machine-driven service workflows where a human cannot sign-in.

Configuration

The FHIR Proxy is configured on installation to be paired to a FHIR Server via a service client. Default roles are added to the application and are configured for specific access in the configuration settings section of the function app.

Enabling Pre/Post Processing Modules

By default, no pre/post processors are configured to run. You will need to enable and configure them following the steps outlined in the configuration document.

Date Sort Post-Processor

This post process allows for a date-based sorting alternative on FHIR Servers that do not natively support _sort. The processor implements a top level _sort=date or _sort=-date (reverse chron) query parameter for supported resource queries up to a hard maximum of 5000.

Publish Event Post-Processor

This processor will publish FHIR Server Create/Update and Delete events for affected resources to a configured Event Hub. These events can be subscribed to by any number of consumers in order to trigger orchestrated workflows (e.g. Clinical Decision Support, Audits, Alerts, etc.).

Transform Bundle Pre-Processor

This processing module will transform incoming transaction bundle requests into batch bundle requests and maintain UUID associations of contained resources. This is an alternative to updating FHIR Servers unable to handle transaction based requests.

Participant Filter Post-Processor

This processing module will filter resources linked to a user registered in a Patient Participant Role such that only records referencing that user's Patient resource are returned. Note: this only filters patient-based linked resources. You can use this module as a basis for building your own security filtering (e.g., filtering records for a user in a Practitioner Participant Role linked to a Practitioner resource, etc.).

Consent Opt-Out Filter

This module adds the ability to deny access to FHIR Server resources for patients who have elected to OPTOUT everyone or specific individuals and/or organizations from access to their medical data.

Everything Patient Pre-Processor

This pre-preocessing module implements a limited $everything at the patient level. It returns the Patient and up to 5000 related resources for the Patient. Paging or other query parameters are not currently supported.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

FHIR® is the registered trademark of HL7 and is used with the permission of HL7.