Smile CDR v2023.08.PRE
On this page:

4.1SMART on FHIR Apps

 

Smile CDR can be used as a host for deploying SMART on FHIR Apps.

On this page, we will be using Smile CDR to launch a SMART on FHIR App (or SMART App). This page assumes that you have a local Smile CDR installation you control, and that you are able to install a local server to host the application as well.

To accomplish this, we will be using the following components:

  • We will use the SMART Pediatric Growth Chart application as a demonstration app. This app is a great demonstration of how SMART on FHIR works.

  • We will use Smile CDR's SMART Outbound Security module as a SMART IdP (OAuth2/OpenID Connect server): In this role, users attempting to sign into a SMART App will be presented with an app login screen provided by Smile CDR. This login screen will ask for credentials then verify that the user wishes to authorize the app to access data on their behalf, and that the user has appropriate permission to actually access the FHIR data that the app claims to need.

  • We will use Smile CDR's FHIR Endpoint module as a FHIR Server: In this role, Smile CDR will respond to requests for FHIR data from the app. When the user signs in through the OAuth2 server, they receive a bearer token. This token is checked with each request to ensure that the user has appropriate permissions for the data they are trying to access. In addition, all access to data is logged in the audit log.

SMART on FHIR Architecture

4.1.1Accessing the Web Admin Console

 

First we need to sign into the Web Admin Console. This console can be used by administrators to configure almost all aspects of the system. Access the console using the appropriate URL:

In a fresh self-hosted instance the username will be admin, and the password will be password. You should change these credentials before using Smile CDR in production with real data. To log into the console, enter your admin credentials. http://localhost:9100

4.1.2Creating a Client Definition

 

To support launching and authorizing a SMART App, we will need to create a client definition.

In the Web Admin Console, click on Config OpenID Connect Client. You should now see a window like the following:

OpenID Connect Clients

If you do not see the growth_chart client in the list, you will need to create it.

Creating a Client Definition in Web Admin Console

Note: Alternatively, you may choose to create a client definition with Smile CDR's JSON Admin API.

Create a new client definition by clicking on Create Client. Set the following details:

Client ID
Client Name
Client Secret (none)
Authorized Grant Types Authorization Code
Access Token Validity
Refresh Token Validity
Authorized Redirect URLs
SMART Scopes: Scopes
SMART Scopes: Auto-Approve Scopes (none)

Creating a Client Definition with JSON Admin API

Instead of manually creating the client definition, you can also use the JSON Admin API to create a client definition with the following cURL command:

curl -X PUT \
  --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
             "clientId": "growth_chart",
             "clientName": "Growth Chart",
             "allowedGrantTypes": [ "AUTHORIZATION_CODE" ],
             "accessTokenValiditySeconds": 3600,
             "refreshTokenValiditySeconds": 86400,
             "registeredRedirectUris": [ "http://localhost:9201/resources/cdr-smart-apps-growth-chart-app/" ],
             "scopes": [ "openid", "launch", "patient/*.read" ]
}' http://localhost:9000/openid-connect-clients/Master/smart_auth/growth_chart

4.1.3Enabling SMART on FHIR Requests

 

To enable the SMART on FHIR App to submit FHIR requests to Smile CDR, we will need to make a few additional configuration changes as described below.

Enable Anonymous Access to Capability Statement

If access has not already been granted to the FHIR Endpoint for the anonymous user, you can either enable full read-access using the instructions here, or simply enable the FHIR_CAPABILITIES permission for user anonymous.

Enable CORS for SMART Authentication Module

  1. In the Web Admin Console, click on Config Module Config and select the SMART on FHIR Outbound Security Module that will be used to authorize users (the sample configuration includes one named smart_auth that can be used here).
  2. In the configuration window, scroll down to the Cross-Origin Resource Sharing (CORS) section and set CORS Enabled to Yes.
  3. Click Save and then Restart.

Enable SMART Authentication for FHIR Endpoint Module

  1. In the Web Admin Console, click on Config Module Config and select a FHIR Endpoint Module (the sample configuration includes one named fhir_endpoint that can be used here).
  2. In the configuration window, scroll down to the Dependencies section and for the OpenID Connect Authentication dependency, select the SMART on FHIR Outbound Security Module configured above (e.g. smart_auth if using the sample configuration).
  3. Click Save and then Restart.

NOTE: The OpenID Connect Authentication dependency above can be either a SMART on FHIR Outbound module or SMART on FHIR Inbound module, depending on how the authentication server was defined. See Accepting Internal Access Tokens for more information.

4.1.4Install Growth Chart App

 

To install the Growth Chart app, follow these steps:

  1. Check out the application codebase from the project GitHub repository. You can use a Git client to check it out, or you can click on the Code Download Zip buttons to download a snapshot.

  2. Open the file package.json in an editor and look for the following string -p 9000. Change this to be -p 9201. This changes the default port used to serve the app from port 9000 (which is already in use on a default Smile CDR installation) to port 9201.

  3. Execute the following command to build the project.

npm install
  1. Execute the following command to start the server.
npm start

4.1.5Create Some Test Data

 

Next, we will upload some test data to our FHIR server in order to provide the app with something to visualize. You can do this using a standard REST client such as Postman or Insomnia.

Note that in a default Smile CDR installation the FHIR Endpoint module on port 8000 is secured to allow HTTP Basic authorization. To perform the operations in this section, you can configure your REST client to use HTTP Basic Auth with your admin credentials (admin / password by default), or you can simply manually add the Authorization header shown below.

Create a Patient

First, create a Patient resource. We will use the ID of patient-a for this resource. Feel free to replace this with your own name and insert your own (or other) demographics if you would like!

Perform the following HTTP operation:

  • URL: http://localhost:8000/Patient/patient-a
  • Verb: PUT
  • Header: Authorization: Basic YWRtaW46cGFzc3dvcmQ= (this creates the credentials admin/password)
  • Header: Content-Type: application/fhir+json
  • Body:
{
  "resourceType": "Patient",
  "id": "patient-a",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2020-11-10T20:24:48.194+00:00"
  },
  "name": [ {
    "family": "Smith",
    "given": [ "John" ]
  } ],
  "gender": "male",
  "birthDate": "2020-01-01"
}

Create a Height Observation

Perform the following HTTP operation:

  • URL: http://localhost:8000/Observation/patient-a-height-1
  • Verb: PUT
  • Header: Authorization: Basic YWRtaW46cGFzc3dvcmQ= (this creates the credentials admin/password)
  • Header: Content-Type: application/fhir+json
  • Body:
{
  "resourceType": "Observation",
  "id": "patient-a-height-1",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "8302-2",
      "display": "Body Height"
    } ]
  },
  "subject": {
    "reference": "Patient/patient-a"
  },
  "effectiveDateTime": "2020-01-05T00:00:00Z",
  "valueQuantity": {
    "value": 48.0,
    "unit": "cm",
    "system": "http://unitsofmeasure.org",
    "code": "cm"
  }
}

Create a Weight Observation

Perform the following HTTP operation:

  • URL: http://localhost:8000/Observation/patient-a-weight-1
  • Verb: PUT
  • Header: Authorization: Basic YWRtaW46cGFzc3dvcmQ= (this creates the credentials admin/password)
  • Header: Content-Type: application/fhir+json
  • Body:
{
  "resourceType": "Observation",
  "id": "patient-a-weight-1",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "3141-9",
      "display": "Body weight Measured"
    } ]
  },
  "subject": {
    "reference": "Patient/patient-a"
  },
  "effectiveDateTime": "2020-01-05T00:00:00Z",
  "valueQuantity": {
    "value": 3.0,
    "unit": "kg",
    "system": "http://unitsofmeasure.org",
    "code": "kg"
  }
}

4.1.6Enable SMART Authorization on FHIR Endpoint

 

By default, Smile CDR enables only HTTP Basic Auth on the FHIR Endpoint, so we need to configure it to support SMART Authentication as well.

  • Enter the Web Admin Console at http://localhost:9100

  • Navigate to Config Module Config

  • Select the fhir_endpoint module from the list

  • Make the following configuration changes:

    • Auth Open ID Connect // OpenID Connect Security: Yes

    • Dependencies // OpenID Connect Authentication: smart_auth

  • At the top of the page, click Save then Restart

4.1.7Install a Launch Context Script

 

Like most SMART on FHIR apps, the Growth Chart app relies on a feature of the SMART on FHIR specification called Launch Contexts to determine the ID of the Patient resource it should try to load. You can see that it will use this because it has the launch scope in its list of allowed scopes in the client definition above.

In a real world scenario, you would need some mechanism for mapping your logged-in users onto specific FHIR resource IDs. For this demo, we will simply add a script to the SMART Outbound Security module that hardcodes the Patient context.

  • Enter the Web Admin Console at http://localhost:9100

  • Navigate to Config Module Config

  • Select the smart_auth module from the list

  • Find the section labelled SMART Callback Script and paste the following contents into the Post Authorization Script (Text) box:

/**
 * This function is called just prior to the creation and issuing of a new
 * access token.
 *
 * @param theUserSession The authenticated user session (can be modified by the script)
 * @param theAuthorizationRequestDetails Contains details about the authorization request
 */
function onTokenGenerating(theUserSession, theAuthorizationRequestDetails) {

   // Hardcode the launch context ID to be the Patient with ID 'patient-a'
   theUserSession.addLaunchResourceId('patient', 'patient-a');

}
  • At the top of the page, click Save then Restart

4.1.8Launch SMART on FHIR Growth Chart App

 

Now that we've created a client definition and updated the appropriate module configurations, we're ready to launch a SMART on FHIR App.

The following URL is a SMART Launch URL. Note the following parameters:

  • iss – The base URL for the FHIR endpoint. The app will load the server capability statement from this endpoint, which allows it to figure out where to authorize.
  • launch – This is intended to be a one-time nonce. In a real scenario this would be randomly generated.

You may open the following URL in a browser: http://localhost:9201/launch.html?iss=http://localhost:8000&launch=A000

This URL will immediately redirect you to a Smile CDR login screen. The user whose credentials you use to log in must have the appropriate permission to read clinical data from the repository.

Use your admin credentials to sign in. You will be presented with a screen asking you to confirm that you wish to grant permission to the app.

Authorizing Application

Grant the app permission by clicking Authorize. The SMART on FHIR Growth Chart App will then launch. Neat!

Growth Chart SMART on FHIR App