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

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.
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).
  • Ensure that the system's users have access to at least one configurable launch URL for Ocean. These URLs should accommodate variable path names based on factors such as the Ocean site, the intended Ocean action, and other relevant parameters.
    • A full list of 'action' parameters for SMART launching into Ocean 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

Systems should also:

  • Provide the Base64-encoded value for the Ocean site's Shared Encryption Key as the value for an "oceanSharedEncryptionKey" attribute in the SMART launch access token.
    • This parameter eliminates the need for users to manually input their site's Shared Encryption Key in their web browser for each contextual launch. While it can be omitted if a clinic pre-configures user web browsers by storing the Shared Encryption Key in the browser's "localStorage," it is usually mandatory. Hospital-based browsers often do not retain localStorage across user sessions due to privacy considerations.
    • More information on SMART launch providers is provided here
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.
  • Ocean reads this patient information, with permission from the EHR, by requesting "scopes" to read data from the EHR's FHIR endpoints.
  • 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.
Integration Requirements for Patient-Contextual Launch in Ocean Systems

In addition, to support patient-contextual launch, systems must adhere to the following requirements:

  • Support FHIR R4 for Patient.read Endpoint:
    • Integration should include support for the Patient.read endpoint as part of the SMART App Launch context, following FHIR R4 standards.
  • Include "patient" Parameter in SMART Launch Acess Token:
    • Ensure the provision of a "patient" parameter in the SMART launch access token to enable seamless patient-contextual launches.
  • Adherence to FHIR Conventions for PHI Storage:
    • Adhere to established FHIR conventions for the storage of relevant PHI used by Ocean. This includes the use of "JHN" Health Number identifier and Version Code identifier for Ontario patients.
  • Optional: Support FHIR R4 /Patient/[id]/$everything Operation:
    • Optionally support the FHIR R4 /[/Patient/[id]/$everything operation to pre-populate medications, allergies, medical history, and chart attachments.
Sequence of Events for Users
    1. A user is signed into the EHR system.
    2. The user clicks on an "Ocean" launch button in the EHR's UI.
    3. 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).
    4. 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 current patient.
      • Ocean checks whether the EHR user has already been linked to an Ocean account.
    5. If the user has not yet linked their EHR account to Ocean, a sign-in prompt is shown:
    6. Once the account is linked, from that point onwards the single sign-on is automatic.
    7. Next, if a patient was specified, Ocean asks the EHR for information about the current patient (using the EHR's FHIR APIs).
    8. 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).

Allowlisting

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

Please send the following values to the Ocean Support email 'support@oceanmd.com' so that we can create the allowlist entry for your launch system:

  1. The Server URL:
    • Provided as the initial "iss" parameter during the SMART launch. This value should also correspond to the FHIR API server.
  2. Client ID:
    • The unique unguessable "client_id" for Ocean, as randonly 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.)
  3. Authorization Endpoint:
    • The OAuth 2.0 "/authorize" endpoint.
  4. Token Endpoint:
    • the OAuth 2.0 "/token" endpoint.
  5. Token Issuer URL:
    • The "iss" value proivided within the signed JWT claims set, within the id_token value of the authorization token.
  6. The URL and the response body for the publicly-accessible ".../.well-known/smart-configuration" (if supported).
  7. 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.)

Have more questions? Submit a request