Authenticating your app

Here we describe how a client library or application communicates and authenticates with the PerformanceBridge API. Environment variables are used below as placeholders. Those building applications that will use the API, but not be deployed on PerformanceBridge infrastructure will need to set them based on the information provided for the PerformanceBridge platform to which you're connecting.

Low-level Communication

The PerformanceBridge API uses HTTP as the core means of its communication. The configuration is typically communicated to applications via the PB_API_URL environment variable when building a PerformanceBridge application. This variable and all other secrets/configuration information is scoped to the application's container. If your client library is intended to be used in another context you will have to choose how to determine/set the protocol.

Authentication Scheme

PerformanceBridge API uses an HMAC based approach to authenticating clients. This is very similar to how Amazon Web Services authenticates clients. The core element is an HMAC secret key. Both the client and server have the HMAC secret key, but it is never transmitted in an API request. For PerformanceBridge applications the secret key is available in the PB_API_SECRET_KEY environment variable. It is generated as part of application deployment. If you are not building a PerformanceBridge application or are in a development environment the key will need to created and exchanged manually, i.e., human intervention. This is a per PB instance key. In other words, the key you used to develop with will not be the key used in production.

The secret key is used in conjunction with a canonical application name, datetime stamp, and the active parameters of the request to build an authorization header for any request. Active parameters refers to those parameters that would have an effect on the response contents. The hmac in the authorization header must be base64 encoded. Here is a list of steps and code example to make a valid request to the query portion of the API:

  • Create your query string/parameters
  • Create a content hash of your query string/parameters - SHA512 of query string in base64
  • Get the current datetime in iso8601
  • Hash your authorization HMAC - SHA512 hmac_secret_key + request_time + content_hash in base64
  • Create an authorization header value - PB appname:hmac
  • Set the Content-Hash, Content-Type, Date, and Authorization headers

Here's the above as a sample request on the SELECT endpoint using an HMAC secret key of 89oa7u3wr9o8aj3wfo89aj9w38fjawo938fj for an app named tutorial:

POST /pb/api/query/select HTTP/1.1
Host: pbapi.example.com
Content-Type: text/json
Content-Hash: UYShY0WAaD/+x+ldTSXUeSTgworyYfkNW18pYRp61fQRWIVwRTUbosrAW4tSGgRqXEoIWg+OBCX7A1Ag0o3hKg==
Date: 2021-07-22T09:36:56-04:00
Authorization: PB tutorial:vbrCXddMr/GMNTEMUZuMZDHIA9Gt4ls+7JQvYl1TTOxRv1vaLVPqfSqc2BrcvbDg2CLL0nufaE2BlD+wpCdwcw==

{"select":"select * from rad_exams limit 1","parameters":[]}

The PerformanceBridge API in turn checks that the date sent by the client is within a minimal range of the datetime of the server at the time of processing the request. The intent of which is to mitigate replay attacks. As such the client's machine should keep consistent time. Then it recreates the authorization hmac in the same way using the secret key it has for the specified application. If the authorization hmac does not match or the date header is beyond the timing threshold then it returns a 401 (unauthorized) response.

Note - PerformanceBridge never uses self signed certificates. You should not turn off SSL validation in your client library.

Authorization Scheme

The authorization model is built around what application is using the service. An application, as specified in the Authorization header is a canonical name registered with PerformanceBridge. Each application has credentials to access data and the API uses those credentials when performing any operation. In other words, the API runs as the requesting application and not as a super user. Generally speaking, the applications authorization consists of access to read from the clinical data model and read/write to its own application specific schema.

Examples

The following are sample implmentations of the above steps in various languages. Please keep in mind you will want to include HTTP error handling, response parsing, etc. Additionally, some libraries may have extra steps required for SSL communication.