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
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.
- User selects an app from a Commure-enabled EHR interface or the Commure Platform. Apps do not have to directly integrate with any EHRs.
- Commure redirects the user's browser to the app, passing the
- 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.
- Commure authenticates the user using the hospital's SSO system. Apps do not have to directly integrate with hospital SSO.
- Once the user is authenticated, Commure returns an authorization
codeto the app. The app then sends this
codeto Commure's token endpoint in exchange for an
access_tokenand any SMART context information that is available.
- The app includes the
Bearertoken in the
Authorizationheader of any subsequent FHIR API requests sent to the Commure Platform.
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
To enable Client Credentials...
- Log in to the Developer Portal.
- Navigate to
- If you already registered your application and it was not created as a
webtype application, you will need to replace it with a new application (created in the next step).
- Create a new application by clicking
- For the question
What kind of app are you building?, answer
- 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.
- At the bottom right of the screen, there should be a checkbox that reads
Allow Client Credentials. Ensure that this is checked before clicking
Registerto create the application.
- To use Client Credentials with Commure, follow the documentation on Authentication
/auth/tokenby clicking the
Client Credentialsbutton to reveal details.