Ocean SMART App Launch Overview (SMART on FHIR EHR Contextual Launch) – OceanMD

Introduction

Ocean uses the SMART App Launch industry standard to support single-sign-on (SSO) and patient-contextual launch from an electronic health record (EHR) or other health system.

Single Sign-On

The SMART launch framework allows an authenticated person using a trusted third-party health system to open a specific application or page within Ocean without having to manually sign in to Ocean. Instead, the user's EHR credentials can be used to securely and automatically sign in as their corresponding Ocean user.

Ocean adheres to the Open ID Connect standard to ensure this single sign-on process is secure.

Patient Contextual Launch

In addition to SSO, the SMART launch can optionally pass information to Ocean that is related to the EHR's currently-selected patient. The patient information includes the EHR's MRN, name, health number, gender, date of birth, contact information and other clinical information when available.

Some use cases for the patient contextual launch include:

Opening the patient's "Ocean Patient Dashboard" to view a summary of Ocean information related to this patient, including active eReferrals, eConsults, questionnaire results and so on. The dashboard also serves as a convenient launch point for performing other actions, such as initiating a referral.
Viewing the patient in Ocean's Health Map.
Creating a new eReferral that is pre-populated with the patient's demographic and clinical information based on the EHR chart.
Using Ocean to email a secure message link or questionnaire directly from the EHR chart.

Ocean reads this patient information, with permission from the EHR, by requesting "scopes" to read data from the EHR's FHIR endpoints.

Sequence of Events for Users

A user is signed into the EHR system.
The user clicks on an "Ocean" launch button in the EHR's UI.
The launch button opens Ocean in a new web browser tab or window. The launcher supplies Ocean with a URL containing the basic launch credentials (based on the SMART protocol).
Next, in the background:
- Ocean uses the launch credentials to request authentication information from the EHR using the OAuth 2.0 protocol.
- In response, the EHR provides Ocean with an access token, which provides Ocean with basic information regarding the current EHR user and the current patient.
- Ocean checks whether the EHR user has already been linked to an Ocean account.
If the user has not yet linked their EHR account to Ocean, a sign-in prompt is shown:
Once the account is linked (and from then on in future launches), the single sign-on is automatic.
Next, if a patient was specified, Ocean asks the EHR for information about the current patient (using the EHR's FHIR APIs).
Finally, Ocean redirects to the requested page within Ocean. This page can be either a patient-specific destination, such as the Ocean patient dashboard, or a general destination like the Ocean Portal, depending on the "action" requested by the SMART launch button's launch URL.

The sequence diagram below illustrates the backend interactions between systems that occur to enable the Ocean SMART single-sign-on and contextual launch. (A PDF file is available at the bottom of this article.)

Requirements

To connect to Ocean, launching systems must:

Implement and support the SMART "EHR launch sequence" as the "EHR FHIR Server / EHR Authorization Server" (Ocean is the "App" in this context)
Provide OAuth 2.0 endpoints for the SMART launch.
Adhere to the Open ID Connect protocol as the launching system. As part of the protocol:
- Provide public access to the endpoint: [the-fhir-server]/.well-known/openid-configuration
  - (Ocean accesses this endpoint as part of the Open ID protocol, to ensure it can validate the launcher's JWT signature using the public key that is specified in the configuration's "jwks_uri".)
- Sign the JWT token with the ES256 or RS256 algorithm.
Be capable of launching a modern web browser (either embedded or via a desktop app linkage)
- The web browser must support Ocean's usage of typical HTTPS session cookies and localStorage for the following URLs:
  - https://ocean.cognisantmd.com
  - https://staging.cognisantmd.com
  - https://test.cognisantmd.com
    - Note: Almost all browsers support these requirements as part of the default configuration, but some EHR installations and hospital settings have specific restrictions on cookie storage.
Provide at least one configurable launch URLs for Ocean for the system's users. These launch URLs must permit variable path names depending on the Ocean site, desired Ocean action, and so on.
- A full list of SMART Launch URLs can be found in the SMART on FHIR Implementation Guidance article.
- Examples of Ocean SMART launch URLs include:
  - Viewing the patient in Ocean's Health Map - https://ocean.cognisantmd.com/sso/smart/auth?siteNum=1234&action=viewMap
  - Opening the patient's "Ocean Patient Dashboard" - https://ocean.cognisantmd.com/sso/smart/auth?siteNum=2000&action=dashboard

In addition, to support patient-contextual launch, systems must:

Support FHIR R4 for the Patient.read endpoint as part of the SMART App Launch context.
Provide a "patient" parameter in the SMART launch access token.
Adhere to established FHIR conventions for storage of relevant PHI used by Ocean, such as the use of the "JHN" health number identifier and the version code identifier for Ontario patients.

Systems should also:

Provide the Base64-encoded value for the Ocean site's shared encryption key as the value for a "oceanSharedEncryptionKey" attribute in the SMART launch access token.
- This parameter saves users from the requirement to manually enter their site's shared encryption key in their web browser during each contextual launch. If a clinic is able to pre-configure all of the applicable user web browsers by storing the shared encryption key within the browser's "localStorage", then it may be omitted here. However, it is typically mandatory since most hospital-based browsers do not retain localStorage across user sessions for privacy reasons.
- More information on SMART launch providers is provided here.

Allowlisting

For security reasons, all health system servers that would like to use a SMART launch into Ocean must be privately allowlisted by an CognisantMD Ocean administrator.

Please send us the following values so that we can create the allowlist entry for your launch system:

The server URL:
- Provided as the initial "iss" parameter during the SMART launch. This value should also correspond to the FHIR API server.
Client ID:
- The unique unguessable "client_id" for Ocean, as randomly assigned by the launching server. (This is the URL parameter supplied by Ocean during the initial SMART redirect back to the launcher's authorization endpoint.)
Authorization endpoint:
- The OAuth 2.0 "/authorize" endpoint
Token endpoint:
- The OAuth 2.0 "/token" endpoint
Token issuer URL:
- The "iss" value provided within the signed JWT claims set, within the id_token value of the authorization token
The URL and the response body for the publicly-accessible ".../.well-known/smart-configuration" (if supported)
The URL and the response body for the publicly-accessible ".../.well-known/openid-configuration"

With the exception of the client ID, all of these values should be available in the EHR server's .well-known/openid-configuration endpoint and/or the FHIR metadata endpoint.

For security reasons, Ocean performs strict validation of the JWT token to adhere to the Open ID Connect precautions. (If any aspect of the JWT token does not pass the protocol, Ocean attempts to provide a helpful error message for troubleshooting.)

Please contact us if you would like to connect your SMART on FHIR-compliant server with Ocean. Plan to provide us with the values listed above.