As part of its Healthcare and Life Sciences vertical the Google Cloud Platform (GCP) provides a set of APIs and data stores that can be used to enable secure storage and retrieval of healthcare data, and also to initiate data processing, data analysis, and so on. APIs and data stores are available for DICOM (imaging), HL7 v2 and FHIR modalities.
In order to gain access to and use these APIs, an OAuth2 access token is needed. For some applications tokens can be generated using the "oauth2l" command line tool (https://github.com/google/oauth2l), but in many cases applications need the ability to generate these tokens programmatically, particularly in long-running services or for situations where data is being accessed by externally-facing applications where exposing sensitive credentials in not appropriate. This project contains an Apigee-based solution for enabling creation of these access tokens using the OAuth 2.0 client credentials grant.
This solution is comprised of two pieces:
- An Apigee API proxy called "oauth-b2b", which implements the OAuth 2 client credentials grant protocol. This API proxy returns a bearer token which can be used to make requests for data.
- An Apigee proxy called "fhir-endpoints", which validates a token generated using "oauth-b2b" and formats a data request to a Cloud Healthcare FHIR API endpoint.
Combined with application-specific configuration information governing which APIs and data stores can be accessed, and Apigee's own extensive functionality for developer management, traffic mediation and threat detection, a highly secure and fully managed solution for controlling access to healthcare data can be created.
This project is being released under the Apache 2 license. Please see the LICENSE file in this repository for details.
The code in this repository is intended primarily as a template for your own implementation. We strongly suggest that you review the code before deployment to ensure that it is suitable for your specific requirements. In particular:
- Because traffic management requirements are very specific to the customer and use case, the Apigee proxies in this repository do not implement traffic management or threat detection policies.
- Generally speaking, the code in this repository is oriented more toward server-side applications within a healthcare organization (although there's no reason that this code can't be used as a foundation for other use cases). For example, this code uses the OAuth 2 client credentials grant, which does not accept user identify parameters (userid and password) and is not appropriate for places where access is to be scoped to particular individuals (patients, providers, etc.). This code also does not provide for any sort of end user consent management; if such features are needed, you may want review Apigee's open-source Health APIx solution (https://github.com/apigee/flame).
PLEASE NOTE: THIS IS NOT AN OFFICIALLY SUPPORTED GOOGLE PRODUCT.
The following prerequisites are needed:
- An Apigee SaaS installation that supports encrypted KVMs and Node.js HostedTarget functionality (note that token generation has not been tested using Apigee's legacy "Trireme" Node.js implementation). The Cloud Healthcare APIs are available in Google Cloud Platform only. Apigee has a free usage tier and other reasonably-priced pricing tiers; for more information and links to pricing info, see https://cloud.google.com/apigee-api-management/.
- An available Apigee organization and environment. See your Apigee administrator or API program manager to obtain this information.
- An Apigee login with sufficient privileges to import and deploy API proxies, create or modify encrypted Apigee key-value maps (KVMs), and create or configure Apigee Developer and Developer Application entities.
- The GCP SDK or an installation of the "gcloud" command line tool.
- Apache Maven, version 3 or later.
- A GCP IAM service account key for each application which will access the Cloud Healthcare APIs. More information on this is provided later in this document.
In addition, depending on your installation you may need to generate keys and certificates for use with TLS. You should have these available before you begin installation.
Most of the "heavy lifting" for the installation process is performed by Maven and the Apigee Maven Deploy Plugin. You may wish to become familiar with this plugin, and some of Apigee's other related Maven plugins.
It's important to note that the build process uses Maven's "profile" functionality to enable environment-specific deployments to be configured. The POM in this directory contains the profiles for "dev" and "prod"; these profiles specify (for example) the Apigee management API endpoint. You should review this before starting the deployment process.
Information on how to create IAM service account keys can be found in the GCP documentation. Service keys you create for use with the Cloud Healthcare APIs should have the appropriate permissions for the type of data to be accessed (DICOM or FHIR, for example) and the nature of the access to be granted (read only, read/write, etc.)
Note that you will not be able to assign Cloud Healthcare API permissions to a service account key unless the Healthcare API has been enabled for your project.
Apigee developer and developer application entities provide metadata about applications that can access APIs hosted in Apigee and the developers that created them. You can use the Apigee UI or its management API to create these entities; for more information, please see the corresponding Apigee documentation.
Once developer and developer application entities have been created for an application that should access the Healthcare API, you can create metadata on the application entity to indicate which project, location, dataset and store are to be made available. You add this information to the Developer Application entity using Apigee's "custom attributes" feature.
Four values need to be created in custom atributes for each application:
- "project" - the name of the GCP project in which the Healthcare API is hosted.
- "location" - the location in which the Healthcare API dataset was created
- "dataset" - the name of the dataset to which access is to be granted
- "fhirstore" - the name of the FHIR data store to which access is to be granted.
Once these values are set, the API proxies provided in this solution will automatically map them to the appropriate Healthcare API calls.
To make these proxies available in your Apigee environment, execute the following command from the repository's root directory:
mvn clean deploy -P <profile-name> -Dusername=<apigee-userid> -Dpassword=<apigee-password> -Dorgname=<apigee-orgname> -Dapigee.config.options=create
where "profile-name" is the Maven profile name, "apigee-userid" and "apigee-password" are the credentials for the Apigee account to be used when importing and deploying proxies, "apigee-orgname" is the Apigee organization name and "apigee.config.options" is used for creating the KVM configuration in Apigee
In this example the Apigee environment name to be used to deploy the proxies is specified in the Maven profile, but this can be overridden on the command line as well.
Once the Maven build is successful, two proxies (fhir-endpoints and oauth-b2b) will be deployed. Along with that, an Encrypted KVM called iam_credentials will be created. You can view it using the UI by clicking Admin --> Environments on the left menu. Make sure you select the appropriate environment
To create the IAM entry within this KVM, run the following curl command
curl -X POST \
https://api.enterprise.apigee.com/v1/organizations/<org>/environments/<env>/keyvaluemaps/iam_credentials/entries \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <base64-encoded-username-and-password>' \
-d '{ "name" : "<app>", "value" : "<creds>" }'
where "app" is the application name for which the credentials apply, and "creds" is the complete IAM service account key to be used for this application. You will need to update the org, env, authorization (base64 encoded value of your Apigee username:Apigee password), app and creds
Once the above curl is successful, you should be able to see the KVM entries in the UI
Once the complete solution is deployed and the KVM entries are created, you can generate an OAuth 2 token using a "curl" command similar to this one:
curl -X POST \
https://<org>-<env>.apigee.net/oauth2/accesstoken \
-H 'Accept: application/json' \
-H 'Authorization: Basic <base64-encoded-api-key-and-secret>' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{ "grantType" : "client_credentials", "scopes" : "user/*.read" }'
With the token you can retrieve FHIR entities from the FHIR store using a command similar to this one:
curl -X GET \
https://<org>-<env>.apigee.net/v1/hcapi/<entity-name>/<entity-id> \
-H 'Accept: application/fhir+json;charset=utf-8' \
-H 'Authorization: Bearer <access-token>' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/fhir+json;charset=utf-8'
When an application requests an Oauth access token to access the Cloud Healthcare FHIR API, the steps shown in the diagram below occur:
API Cloud Healthcare
Consumer Apigee FHIR API
--------- ---------- --------------
request token ----------------> validate access
using API key to Cloud Healthcare
and shared secret FHIR API
Retrieve application
Cloud Healthcare API
config
Retrieve appropriate
IAM service account key
Get IAM access token
using information from
the GCP service account
key
Generate Apigee access
token and store IAM
token as related
metadata
token response <-------------- Return Apigee token
Apigee uses its built-in capabilities to identify the requesting application based on the API key and secret presented in the token request. Once the application is identified, the information about the Cloud Healthcare API stores the application is eligible to access are retrieved, the appropriate IAM service key is retrieved from encrypted storage, and an OAuth2 token is generated. Apigee then generates an access token of its own, associates the Cloud Healthcare API info and OAuth2 token with that self-generated token, and returns the self-generated token to the requesting application. At no point is information about GCP, the service account used, or the configured FHIR store provided to the requesting application.
When that application makes a request for data, the token is provided in the HTTP "Authorization" header as a "Bearer" token:
API Cloud Healthcare
Consumer Apigee FHIR API
--------- ---------- --------------
Use bearer token
to
GET /Patient/1 --------------> Validate token
Retrieve associated
token metadata
(project, location,
dataset, FHIR store)
and IAM access token
Format request to
configured
Cloud Healthcare FHIR
API with OAuth2 token
Issue Cloud Healthcare
FHIR API request -------> Receive FHIR request
Validate IAM token
Retrieve data
Receive response <------- Return data
from Cloud Healthcare
FHIR API
Receive response <------------- Send response to client
- The Apigee API proxies in this solution do not currently contain any traffic management policies. You can easily add these and configure them to your specific requirements using the Apigee UI or your desktop text editor.
If you run into any problems or issues with this solution, please file a ticket in the Github repository.
In addition, you can find help with general Apigee-related questions in the Apigee documentation or in the Apigee Community