Note: Illustrative flow and content is adapted from the International Patient Access Specification ... significant extension and adaptation will be required.

Gaining Access to Patient Records

An application SHALL receive authorization to access a patient record using the SMART App Launch Protocol. Below is a high level description of the use of the SMART on FHIR.

Initiating the app launch from an EMR

text needed

App processes upon launch

A client application gets access to a patient record by following this general sequence of steps:

  • Register itself as a client application with the endpoint.

    • This may require a manual step on the part of the user or the developer, or the endpoint may support automatic registration (see OAuth 2.0 Dynamic Client Registration Protocol).
    • If the application supports automatic registration, the [url]/.well-known/smart-configuration will specify the endpoint.
    • Note: Most healthcare systems exercise control over which clients can access healthcare records, and automatic registration is not supported.

  • Identifying the appropriate endpoint (url) for the IPA-compatible API.

    • Note: This specification does not specify how to find the endpoint; different countries will have different arrangements.

  • Fetch the system capability statement from [url]/metadata and check that it implements the IPA API

  • Fetch the endpoint configuration from [url]/.well-known/smart-configuration.

  • Follow the Smart App Launch Protocol using the authorization endpoint from the smart-configuration file and request the launch/patient scope.

  • At the end of the SMART App Launch Protocol, the application will have a token that provides access to a single patient record. Now, use that to retrieve patient information.

Scope must be requested by apps at launch

SMART on FHIR’s authorization scheme uses OAuth scopes to communicate (and negotiate) access requirements. Scopes work as described in the SMART on FHIR specification.

In general, as specified by the IPA specification:

  • Servers MAY limit clients’ scopes to those configured at registration time and SHOULD allow to select a subset of the requested scopes when initially launching an app.
  • Apps SHOULD inspect the returned scopes and accommodate the differences from the scopes it requested and registered.

Scope: Ontario eReferral

Ontario eReferral solutions typically request the following scopes from servers when launched to support single sign on (SSO) and access to information needed to populate the referral forms:

requested scope purpose
launch, launch/patient & launch/encounter Request launch context from the server
openid & fhirUser Request permission to retrieve information about the current logged-in user to support SSO using OpenID Connect
patient/*.rs or patient/*.read Request permission to read and search any FHIR resource for the current patient

Launch context provided by server to app

Two key steps:

  • Apps that launch from the EHR will be passed an explicit URL parameter called launch.
  • When requesting the access_token, launch is exchanged JSON context parameters.
{
  "access_token": "secret-xyz",
  "patient": "123",
  "fhirContext": [{"reference": "ServiceRequest/123"}]
}
Launch context parameter Example value Meaning
patient 123 String value with a patient id, indicating that the app was launched in the context of FHIR Patient 123. If the app has any patient-level scopes, they will be scoped to Patient 123.
encounter 123 String value with an encounter id, indicating that the app was launched in the context of FHIR Encounter 123.
fhirContext [{"reference": "ServiceRequest/123"}] Array of objects referring to any resource type other than “Patient” or “Encounter”.

Launch context: Ontario eReferral

  • fhirContext MAY be received with a reference to a preliminary/pending eReferral request.
  • Relevant information in the patient chart MAY have been selected for attachment to an eReferral prior to launching the app, in this case, the server MAY:
    • Allow this to be retrieved as a Bundle type searchset using [base]/Patient/[id]/$everything.
    • Or allow this to be retrieved as a Bundle type searchset using GET: [base]/ServiceRequest?_include=ServiceRequest:supportingInfo.

SMART on FHIR Obligations and Capabilities:

Canadian servers and clients conformant with this guide:

  • SHALL exchange FHIR resources that conform to minimum requirements specified in the Canadian Baseline FHIR profiles when representing clinical information exchanged between servers and clients.
  • SHOULD enable read access to applicable FHIR resources using a RESTful FHIR API, a summary of recommended resources is provided on Profiles ).
  • the SMART on FHIR obligations and capabilities.

This section documents the SMART on FHIR obligations and capabilities. The Conformance page documents the support for IPA Profiles and their FHIR interactions.

SMART on FHIR Server Obligations

A server SHALL host a smart-configuration file at [url]/.well-known/smart-configuration that is available to both authenticated and unauthenticated clients.

SMART on FHIR Server Capabilities

Servers supporting apps using EHR launch SHALL support the following SMART on FHIR capabilities:

Servers MAY support the other SMART on FHIR capabilities, such as:

SMART on FHIR Client Capabilities

Client apps will need to support a subset of the SMART on FHIR server capabilities to function:

  • SHALL support launch-ehr or launch-standalone or both.

  • SHOULD support launch-ehr and MAY support launch-standalone.

  • Apps with the technical capability to keep a secret SHALL support client-confidential-asymmetric and MAY support permission-offline.

  • Apps without the technical capability to keep a secret SHALL support client-public and SHALL NOT support client-confidential-asymmetric.

  • Patient-facing apps SHALL support context-standalone-patient and SHOULD support permission-patient.

SMART on FHIR Server Process

The steps described below are typically performed when a server grants access to a client:

  • The server conforms to the SMART App Launch specification and checks that the authenticated user of the application has access.
  • If the client requests access to a patient record, the server checks that the authenticated user of the application has access to the specified record.
  • If the authenticated user is authorized to access multiple patient records, the server typically requires that the user choose a single patient record to share. (A patient often has access to multiple records in the case of a parent or family caregiver).
  • The server ensures that the authenticated user has access to the record.
  • The server returns a Patient FHIR resource identifier as the patient SMART launch context parameter when authorization is granted and includes any patient/ scopes defined by the SMART App Launch Protocol.