Authentication for Commure API

Version
1.0
Release Date
2020-02-06
Status
Live

The Commure Authentication API allows developers to access the information and services needed for their apps to work, while ensuring the security of healthcare data. To accomplish this, our server implements the HL7 SMART App Launch protocol for authentication.

The SMART App Launch protocol is an extension of OpenID Connect. In addition to user identity information like emails and names, the protocol also provides contextual, healthcare-specific information to applications. For example, the SMART protocol allows apps to be launched from within an electronic health record (EHR) system for interacting with a particular patient's medical record. In this example, the SMART protocol provides the app with the FHIR resource ID of the patient in question.

Behind the scenes, the Commure Platform integrates with hospital-run single-sign-on (SSO) systems. This means that users can sign into Commure Platform applications using the same credentials they use to sign into other systems within their healthcare enterprise, such as an electronic health record (EHR). In addition, users will need to sign in only once in order to access all of their applications.

The simplest way to integrate an application with the SMART protocol is to wrap it with the CommureSmartApp React component. The CommureSmartApp component will automatically perform the SMART login flow and provide apps with information about the authenticated user as well as any available SMART healthcare-specific context.

The following is an example of how the SMART App Launch is used to facilitate authenticated Commure Platform requests.

  1. User selects an app from a Commure-enabled EHR interface or the Commure Platform. Apps do not have to directly integrate with any EHRs.
  2. Commure redirects the user's browser to the app, passing the iss and launch parameters.
  3. The app queries the Commure Authentication API (contained in iss) to retrieve its SMART launch configuration. The app then redirects the user to Commure's authorization endpoint.
  4. Commure authenticates the user using the hospital's SSO system. Apps do not have to directly integrate with hospital SSO.
  5. Once the user is authenticated, Commure returns an authorization code to the app. The app then sends this code to Commure's token endpoint in exchange for an access_token and any SMART context information that is available.
  6. The app includes the access_token as a Bearer token in the Authorization header of any subsequent FHIR API requests sent to the Commure Platform.

Related Reading

Reference documentation