Authentication

In this tutorial we will cover an example of authentication using the Commure Authentication API.

Due to the extremely sensitive nature of healthcare data, it is always necessary to authenticate before accessing any Commure FHIR APIs. Commure uses the SMART App Launch protocol and OpenID Connect for authentication.

CommureSmartApp React component

If you are using React, the simplest way to add authentication to your application is to use the <CommureSmartApp /> React component. The following code shows an example, but the Build a New Application page provides the steps in detail.

1import React from "react";
2import { CommureSmartApp } from "@commure/components-data";
3import SMARTClient, { StandalonePreference } from "@commure/smart-core";
4
5const smartClient = new SMARTClient({
6  clientId: "smart_hello_world", // this client_id will work with your Commure tenant
7  scopes: ["openid", "profile", "fhirUser"],
8  redirectUri: "http://localhost:1234/callback", // the app's callback url
9  standaloneLaunch: StandalonePreference.IfNecessary,
10  fhirBaseUrl: "https://api-TENANT_ID.developer.commure.com/api/v1/r4"
11});
12
13export default () => (
14  <CommureSmartApp client={smartClient}>
15    <div>Hello World!</div>
16  </CommureSmartApp>
17);

You will need to replace TENANT_ID with your actual Commure tenant ID, which you can find in the top right menu in your Commure Developer Account.

Other Authentication Options

Apps may also choose to directly implement OpenID Connect or the SMART App Launch protocol to interface with the Commure Authentication API.

Authenticating consists of a handful of HTTP requests with specific query parameters that must be executed in the correct sequence between your application and the Commure Platform.

The following diagram depicts a simplified version of the authentication process. Please refer to the API documentation for details on how to use each endpoint.

1. Request OpenID Connect Metadata

   The app requests the OpenID Connect Metadata endpoint, which returns the authorization and token endpoint URLs.

2. Direct user to Commure Authorization Endpoint

   The app redirects the user's browser to the Authorization endpoint. Commure authenticates the user using the hospital's Single Sign-On process before redirecting the user back to the app's redirect URL, passing an authorization code as a query parameter. If there was a problem authenticating the user, the query string will contain an error instead of the authorization code.

3. Exchange code for access token using Commure Token Endpoint

   The app makes a POST request to the Token endpoint, passing the authorization code in the body. It receives an access token in the response.

4. Use token to access Commure FHIR API

   The app includes the access token in all requests to the FHIR API in order to make requests on behalf of the authenticated user. In the diagrammed example, the app requests the Patient resource with ID 1234.

The OpenID Foundation lists client libraries that they have certified as conforming to the OpenID Connect standard.

Related Reading

Commure Authentication API