SMART Launch Integration

This page provides implementation guidance on how to integrate your SMART applications with MediRecords PMS (EMR).

MediRecords supports the SMART on FHIR^® standard for launching third-party applications in an EMR Launch. This means that an opaque handle to the EHR context is passed along to your app as part of the launch URL. Your SMART app needs to include this handle as a request parameter when it requests authorization to access resources

Prerequisites

Before a SMART app can be launched from MediRecords PMS, the app must be registered with MediRecords. This is to ensure that only trusted applications can be launched from the PMS.
Medirecords would need the following information to register a SMART app in our system.:

1. launch URL - the URL that the PMS will redirect to when launching the app.
2. redirect_uri - the URL that the authorization server will redirect to after the user authorizes the app.
3. scopes - the scopes that the app is requesting access to.
4. client name - the name of the app.

Once registered, the SMART app will be assigned a client ID that it needs to use when requesting authorization.

Smart App Actors

The following actors are involved in the SMART App Launch process:

MR App FE

The Front End(browser-based) component of the MediRecords PMS (EHR) application that the user (e.g., clinician) is logged into. It allows a user to launch the SMART App and provides the launch context to the App.

MR Authorization Server

The authorization server that handles OAuth 2.0 authorisation requests and issues access tokens. It allows the SMART App to request authorisation from the user to access patient health information using the MR FHIR API.

Supported capabilities

The MR Authorization Server supports the following SMART capabilities:

• sso-openid-connect
• launch-ehr
• client-public
• context-ehr-patient
• context-ehr-encounter
• permission-v2
• permission-v1
• permission-patient
• permission-user

The latest list can be retrieved from the smart-configuration endpoint.

MR FHIR API

The FHIR API that provides access to clinical data in the context of the user and patient. It allows the SMART App to read and write FHIR resources using the access token obtained from the authorization server.

SMART App

The third-party application that is launched from MR App. It uses the launch context to request authorisation from the user and access FHIR resources from the MR FHIR API.

SMART App Launch Flow

The following diagram illustrates the SMART App Launch flow The SMART App is launched by a user (e.g., clinician) within the MR App. It goes through an OAuth 2.0 authorization code flow to gain access to FHIR resources from the MR FHIR API. The SMART App must handle the launch context, initiate authorization, and use tokens to access clinical data.

Preconditions:

• User is Logged Into MR App
• The user launches the SMART App by clicking a button in the MR App FE
• MR App FE stashes launch context identified by opaque launch identifier
• MR App FE displays an iFrame or new browser tab with the SMART App’s launch URL.

1. App Launch

   • MR App FE initiates the app launch by calling the SMART App’s launch URL, including:
     • iss: The FHIR base URL of the MR FHIR API
     • launch: An opaque identifier representing the launch context
   • The SMART App receives these parameters via its launch endpoint.
2. SMART Authorization Configuration: smart-configuration endpoint
   • The SMART App uses the iss (FHIR base URL) to retrieve the authorization configuration from the .well-known/smart-configuration endpoint.
   • This includes discovering:
     • authorization endpoint
     • token endpoint
3. Authorization Request: authorize endpoint
   • The SMART App constructs an authorization request to the authorization endpoint, including:
     • client_id, redirect_uri, scope, state, and launch (the opaque id from step 1).
   • The SMART App is redirected to the MR Authorization Server to authorize the SMART App.
4. Authorization Callback
   • On success, the response of the MR Authorization Server is to redirect back to the SMART App’s redirect_uri with:
     • code: The authorization code
     • state: Must be verified by the SMART App
   • On error, the response also redirects back with error parameters.
5. Token Request: token endpoint
   • The SMART App sends a POST request to the token endpoint of the MR Authorization Server to exchange the authorization code for an access token. The request includes the following parameters:
     • client_id, code, redirect_uri, and grant_type=authorization_code.
   • The MR Authorization Server responds with an access token (and optionally a refresh token) and ID token.
6. Read FHIR Patient
   • The SMART App uses the access_token to call the MR FHIR API. Typically, it starts by reading the Patient resource using the patient ID returned in the token response.

ID Token processing

The Token response contains an ID token which is a JSON Web Token (JWT) containing claims about the authentication event and the user. To retrieve th fhirUser ID, the SMART App needs to decode the ID token and extract the relevant claim from the payload. The ID token is base64url-encoded and signed by the authorization server, the SMART App should verify the signature to ensure the token’s integrity and authenticity.

It consists of three parts:

1. JWS Protected Header - contains metadata about the token, such as the signing algorithm used.
2. JWS Payload - contains the claims about the user and authentication event.
   • The payload includes standard claims such as:
     • iss: issuer identifier
     • sub: subject identifier (user ID)
     • aud: audience (client ID of the SMART App)
     • exp: expiration time
     • iat: issued at time
   • It also includes SMART-specific claims such as:
     • fhirUser: the URL of the FHIR resource representing the user (e.g., Practitioner/123)
3. JWS Signature - used to verify the authenticity and integrity of the token.

API End Point

For Prod, MRAPP_BASE_URL is: https://app.medirecords.com.au