For additional information not contained on this site, please visit the Consent2Share on GitHub project website.
Consent2Share is an open source software application sponsored by the U.S. Substance Abuse and Mental Health Administration (SAMHSA). It is designed to support behavioral health data integration with Fast Healthcare Interoperability Resources (FHIR) Servers. Behavioral healthcare, which includes substance abuse and mental health treatment services and providers, faces special privacy regulations that makes the exchange of health care information with other providers more strict than in other areas of healthcare.
Consent2Share implements the concepts and standards of Data Segmentation for Privacy (DS4P). The DS4P Initiative was sponsored and defined by the U.S. Office of the National Coordinator for Health Information Technology (ONC). The implementation of DS4P concepts and standards allows patients receiving behavioral health treatment to share their health information through health information exchanges while protecting patients' privacy.
Technology Stack | Architecture | User Interfaces | Microservices
Supporting Infrastructure Services | Third-party Services
Security | SSL | UAA Private and Public Keys | DISCLAIMER
Sub Projects and Git Repositories | Common Libraries
Java Jar Runner | Spring Boot App Runner | Releases
Development Guide | Deployment Guide
The technology stack used for Consent2Share includes, but not limited to:
- Angular JS
- Angular Material
- Angular CLI
- Node.js
- NPM
- MD2
- RXJS
- TypeScript
- JavaScript - ES6
- HTML5
- CSS3
- Oracle Java 8
- Spring Framework
- Spring Boot
- Spring Cloud
- Apache Maven
- Apache Tomcat
- MySQL
- Flyway
- Docker and Docker Compose
- CloudFoundry User Account and Authentication (UAA) Server
Consent2Share employs a Microservices Architecture which makes it highly scalable and resilient. The majority of Consent2Share microservices are implemented as Spring Boot applications and utilize several Spring Cloud projects including Spring Cloud Netflix and Spring Cloud Security.
The Consent2Share Technical Blueprint can be used as a good reference that shows the big picture of Consent2Share architecture, the technical components, and the high-level interactions among them. Please see the documents in the release page for the applicable version of Consent2Share Technical Blueprint document.
The Consent2Share components can be grouped as the following:
Consent2Share currently offers the following user interfaces: MASTER-UI, C2S UI, PROVIDER-UI and STAFF-UI.
The Master User Interface (master-ui) is a single UI interface to login to Consent2Share as patient, provider, or staff user account.
Source Code Repository: https://github.com/bhits/master-ui
The Consent2Share User Interface (c2s-ui) is a user interface component of Consent2share used by the patient to manage his or her consents.
Source Code Repository: https://github.com/bhits/c2s-ui
The Provider User Interface (provider-ui) is a provider user interface component of Consent2Share used to create and manage patient accounts. Providers can use this to log in, visit their home page, create patient accounts, and manage patient consents.
Source Code Repository: https://github.com/bhits/provider-ui
The Staff User Interface (staff-ui) is an administrative user interface component of Consent2Share used to create and manage user accounts. Administrative staff can use this to log in, visit their home page, create user accounts, and manage user information.
Source Code Repository: https://github.com/bhits/staff-ui
The backend of Consent2Share consists of many microservices that are small and focused on certain domain areas. These microservices provide RESTful API for external access. Some of these microservices also have persistence using MySQL.
The Consent2Share User Interface API (c2s-ui-api) is a Backend For Frontends (BFF) component of Consent2Share.
Source Code Repository: https://github.com/bhits/c2s-ui-api
The Context Handler is a RESTful web service component of Consent2Share. It is responsible for sending XACML response context that includes authorization decisions along with applied policy obligations to Policy Enforcement Point (PEP) components. The Context Handler sends the XACML request context to the Policy Decision Point (PDP). The PDP evaluates the applicable policies either from the Patient Consent Management (PCM) or a Fast Healthcare Interoperability Resource (FHIR) server against the request context, and returns the response context that includes authorization decisions along with obligations of applied policies to the Context Handler. The Context Handler sends XACML response context back to the PEP component. The PDP uses HERAS-AF, an open source XACML 2.0 implementation, for XACML evaluation, and uses either a PCM database as a local policy repository or a FHIR server to retrieve XACML policies that are generated from patients’ consents.
Source Code Repository: https://github.com/bhits/context-handler
The Document Validator Service is responsible for validating C32, C-CDA R1.1 and C-CDA R2.1 clinical documents. It is a RESTful Web Service wrapper around MDHT (Model Driven Health Tools) libraries. It does schema validation for C32 and both schema and schematron validation for C-CDA, and returns the validation results from MDHT in the response. The Document Validator Service is used directly by the Document Segmentation Service DSS to validate the document before and after the segmentation.
Source Code Repository: https://github.com/bhits/document-validator
The Document Segmentation Service (DSS) is responsible for segmenting patients' sensitive health information using the privacy settings selected in the patient's consent. The segmentation process involves the following phases:
- Document Validation: The DSS uses the Document-Validator to verify that the original document is a valid CCD document.
- Fact Model Extraction: The DSS extracts a fact model, which is essentially based on the coded concepts in a CCD document.
- Value Set Lookup: For every code and code system in the fact model, the DSS uses the Value Set Service (VSS) API to lookup the value set categories. The value set categories are also stored in the fact model for future use in the Redaction and Tagging phases.
- Business Rules Management Service (BRMS) Execution: The DSS retrieves the business rules that are stored in a JBoss Guvnor instance and executes them with the fact model. The business rule execution response might contain directives regarding the Tagging phase.
- Redaction: The DSS redacts sensitive health information for any sensitive value set categories which the patient did not consent to share in his/her consent. NOTE: Additional Redaction Handlers are also being configured for other clean-up purposes.
- Tagging: The DSS tags the document based on the business rule execution response from the BRMS Execution step.
- Clean Up: The DSS removes the custom elements that were added to the document for tracing purposes.
- Segmented Document Validation: The DSS validates the final segmented document before returning it to ensure the output of DSS is still a valid CCD document.
- Auditing: If enabled, the DSS also audits the segmentation process using Logback Audit server.
Source Code Repository: https://github.com/bhits/dss
The FHIR Integration Service (FIS) Spring Boot project provides RESTful endpoints to allow applications to publish and retrieve FHIR resources.
Source Code Repository: https://github.com/bhits/fis
The Master User Interface API (master-ui-api) is a Backend For Frontends(BFF) component of Consent2Share.
Source Code Repository: https://github.com/bhits/master-ui-api
The Patient Consent Management (PCM) Service is one of the core components of the Consent2Share application. The PCM provides APIs for patients to manage their electronic consents including consent create, consent edit, consent delete, consent eSignature, and patient provider list management.
Source Code Repository: https://github.com/bhits/pcm
The Policy Enforcement Point (PEP) Service is one of the core components of the Consent2Share application. PEP delegates the access decision to the Context Handler API, and it utilizes the Document Segmentation Service (DSS) for segmenting CCD documents according to a patient's granular consent. PEP gives the same response for both "No applicable consents" and "No documents found" cases to avoid exposing the existence of a patient's consent.
Source Code Repository: https://github.com/bhits/pep
The Patient Health Record (PHR) service is a component of Consent2Share. It is a core service that manages and retains information about each patient. PHR also manages any C32 and/or C-CDA documents that a patient has uploaded to his or her own account for use in testing their consents using the Try My Policy feature.
Source Code Repository: https://github.com/bhits/phr
The Provider Lookup Service (PLS) is responsible for storing provider information as a provider directory. The PLS also provides a RESTful service for querying providers by using several query parameters including first name, last name, gender, address, and phone number for individual providers, and organization name, address, and phone number for organizational providers.
Source Code Repository: https://github.com/bhits/pls
The Provider User Interface API (provider-ui-api) is a Backend For Frontend (BFF) component of Consent2Share.
Source Code Repository: https://github.com/bhits/provider-ui-api
The Staff User Interface API (staff-ui-api) is a Backend For Frontend (BFF) component of Consent2Share.
Source Code Repository: https://github.com/bhits/staff-ui-api
Try My Policy (TRY-POLICY) is a service that enables patients to preview the redacted version of their uploaded clinical document based on the privacy preferences of the consent. It calls the Document Segmentation Service (DSS)(https://github .com/bhits/dss) to (1) segment the patient's clinical document, in the template prescribed by C-CDA-R1, C-CDA-R2, and HITSP C32, and (2) highlight the sections that will be removed in accordance to the patient's consent. Try My Policy transforms the response from DSS into a full XHTML file and provides the Base 64-encoded file in the response JSON. This service is currently utilized in the Consent2Share UI (c2s-ui) for patients to try their policies on their uploaded documents.
Source Code Repository: https://github.com/bhits/try-policy
The User Management Service (UMS) is a component of Consent2Share. It manages the user account creation process, user account activation, user disable, user update, and user demographics persisting. The UMS has been designed to support various roles for a given user such as Admin, Parent, Guardian, Patient, and so on. If it is configured to do so, it also registers user demographics (if the user is also a patient) to a FHIR server.
Source Code Repository: https://github.com/bhits/ums
The Value Set Service (VSS) is responsible for Managing sensitive categories, code systems, value sets, and coded concepts. The VSS also provides a RESTful service to map coded concepts to respective sensitive categories and provide the list of all sensitive categories available in the system.
Source Code Repository: https://github.com/bhits/vss
Consent2Share uses Eureka and Zuul via Spring Cloud Netflix project to facilitate microservice orchestration, dynamic service discovery, load balancing, security, and server side routing. There are two major supporting infrastructure services in Consent2Share based on these projects: Edge Server (Zuul) and Discovery Server (Eureka).
The Configuration Server (config-server) provides support for externalized configuration in the Consent2Share application, including the following components: Consent2Share UI, Consent2Share UI API, Edge Server, Patient Consent Management Service (PCM), Provider Lookup Service (PLS), and Value Set Service (VSS).
Source Code Repository: https://github.com/bhits/config-server
The Discovery Server (Eureka from Netflix OSS) is one of the key tenets of a microservice based architecture. It facilitates Consent2Share microservices to dynamically discover each other and promotes the scalability of the Consent2Share system. It provides the following:
- Registry of Consent2Share service instances
- Provides a means for Consent2Share service instances to register, de-register, and query instances with the registry
- Registry propagation to other Consent2Share microservice (Eureka client) and Discovery Server (Eureka server cluster) instances
Source Code Repository: https://github.com/bhits/discovery-server
The Edge Server acts as a gatekeeper to the outside world. It keeps unauthorized external requests from passing through. It uses Spring Cloud Zuul as a routing framework, which serves as an entry point to the Consent2Share microservices landscape. Zuul uses Spring Cloud Ribbon to look up available services, and routes the external request to an appropriate service instance, facilitating Dynamic Routing and Load Balancing.
Source Code Repository: https://github.com/bhits/edge-server
Consent2Share uses third-party open source service for authentication and authorization service.
Consent2Share uses UAA for authentication, authorization, issuing tokens for client applications, and user account management. Please see UAA Source Code Repository and UAA API Documentation for more detailed information about UAA.
Consent2Share currently uses a fork of the UAA project. This fork is fundamentally the same as the original UAA implementation, but it has some minor styling changes and customization to run behind the Edge Server. It also includes a template uaa.yml configuration file to setup Consent2Share clients, OAuth2 scopes, and a few test users including an admin user in UAA. This fork can be found at https://github.com/bhits/uaa.
HAPI-FHIR is a Java API for HL7 FHIR Clients and Servers.
Source Code Repository: https://github.com/bhits/hapi-fhir
Consent2Share uses OAuth2, OpenID Connect, JSON Web Token (JWT) and SCIM for authorization, authentication, and identity management. CloudFoundry User Account and Authentication (UAA) Server implementation is currently being used and tested with Consent2Share as the authorization server.
The Edge Server is being used as the entry point for public access and acts as a reverse proxy to the OAuth2 resource servers. The security is delegated to the resource servers that are exposed by the Edge Server. Therefore one should exercise great caution when configuring the routes to the microservices. The endpoints that contain sensitive information and do not implement a form of security MUST NOT BE exposed through Edge Server.
For simplicity in development and testing environments, SSL is NOT enabled by default in configurations in Consent2Share components. Please follow the instructions given in particular microservice documentations for enabling SSL if needed to do so in your particular deployment environment. Also, please be mindful about overriding the target endpoints in the default configurations to use https for SSL enabled services.
The Consent2Share microservices that are also configured as OAuth2 Resource Servers use a public key to verify the signature of the JWT Token provided in the Authorization header. This token is generated and signed by UAA using the UAA private key.
These keys need to be securely generated and configured in production environments. The properties that are used to configure the keys:
In Consent2Share microservices:
security.oauth2.resource.jwt.key-value: public key
In UAA:
jwt.token.verification-key: public keyjwt.token.signing-key: private key
Please see UAA Source Code Repository and UAA API Documentation for more detailed information about UAA.
It is strongly encouraged that your program’s Information Security Manager (or equivalent) reviews the security practices as it applies to your implementation of the Consent2Share application in your unique situation. The U.S. Substance Abuse and Mental Health Services Administration (SAMHSA) and BHITS Development Team are not liable for any risks experienced.
Consent2Share is an umbrella project which has several sub-projects.
In User Interfaces, Microservices and Supporting Infrastructure Services sections, we listed services and UIs used in Consent2Share. Each of these services is a sub-project and has its own Git repository.
Also the forked UAA mentioned in Third-party Services section are sub-projects as well and has its own Git repositories.
Additionally, there are other sub-projects listed in the below:
Consent2Share has a set of common libraries that are being used across the microservices. These libraries mostly contain basic utility functions.
Source Code Repository: https://github.com/bhits/common-libraries
NOTE: The common libraries need to be built and installed to the local Maven repository or deployed to the Maven repository used in your enterprise development environment before building any other Consent2Share microservices, in order to prevent any dependency resolution issues.
This project only contains a Dockerfile and an entrypoint.sh script to build a base Docker image for all other Consent2Share microservices that are implemented as Spring Boot applications. This image is essentially based on a opendk Docker image and supports certain environment variables for configuration and runs a configured jar file at startup.
Source Code Repository: https://github.com/bhits/java-jar-runner
As mentioned in the previous sections, Consent2Share is an umbrella project that consists of many microservices. Each microservice and infrastructure component has its own independent source code repository, version, and release cycle. The release of Consent2Share as a whole system is basically a set of tested and compatible microservice releases and the supporting documentation.
The release version numbers are usually specified in <MajorVersion>.<MinorVersion>.<IncrementalVersion> format.
Please see the release page for current releases.
Please see release page to download the document.
Please see release page to download the document.
Please see release page to download the document.
The BHITS project also has a Docker Hub account to house the Docker images built from the public release versions. Please see the Deployment Guide and the infrastructure folder for standing up a Consent2Share running instance and related infrastructure using Docker and Docker Compose.
Additionally, each source code repository also contains README.md instructions and a Dockerfile for building Docker images from the source code.