Authentication for Commure API

Release Date

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. For most browser-side applications, the preferred authentication mechanism will be HL7's SMART App Launch protocol.

SMART App Launch Usage

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

SMART APP Launch Reference documentation

Client Credentials Flow

For a minority of applications, the browser-side authentication flow is insufficient and a server-to-server authentication technique is required. In this case, Commure also supports Client Credentials authentication. It should be noted that this should be avoided wherever possible, as it is inferior in terms of information security to the normal Authorization Code Flow supported by <CommureSmartApp />.

To enable Client Credentials...

  1. Log in to the Developer Portal.
  2. Navigate to My Apps.
  3. If you already registered your application and it was not created as a web type application, you will need to replace it with a new application (created in the next step).
  4. Create a new application by clicking Register.
  5. For the question What kind of app are you building?, answer web.
  6. The interface will show that A client secret will be generated. Note that this means that in your app, even as part of the normal Authorization Code Flow, a client secret must be provided at the time of login. We still have not enabled Client Credentials authentication.
  7. At the bottom right of the screen, there should be a checkbox that reads Allow Client Credentials. Ensure that this is checked before clicking Register to create the application.
  8. To use Client Credentials with Commure, follow the documentation on Authentication under /auth/token by clicking the Client Credentials button to reveal details.
Client credentials enablement screenshot