This page is part of the FHIRcast (v2.1.0-ballot: STU3 Ballot 1) based on FHIR R4. . For a full list of available versions, see the Directory of published versions

App launch scenarios and session discovery

This page contains guidance to implementers and is not part of the normative-track.

A FHIRcast Hub uses a unique hub.topic session id to identify a single session across the Hub, subscribing and driving applications which are engaged in the shared session. The hub.topic must be known by a system for it to participate in the session. Typically, the Hub defines the hub.topic.

The HL7 SMART on FHIR app launch specification enables the launched, synchronizing app to discover the hub.topic, because the SMART OAuth 2.0 server provides it during the OAuth 2.0 handshake as a SMART launch parameter. Use of SMART requires either that a synchronizing app supports the SMART on FHIR specification and specifically either be launched from the driving app or use the hub’s authorization server’s login page.

Once the hub.topic and url to the hub (hub.url) are known by the synchronizing app, the subscription and workflow event notification process proceeds per the FHIRcast specification, regardless of the specific app launch used.

The use of the SMART on FHIR OAuth 2.0 profile simplifies, secures and standardizes FHIRcast context synchronization. While more creative approaches, such as the alternate app launch and shared session identifier generation algorithm are possible to use with FHIRcast, care must be taken by the implementer to ensure synchronization and to protect against PHI loss, session hijacking and other security risks. Specifically, the hub.topic session identifier must be unique, unguessable, and specific to the session.

SMART on FHIR

FHIRcast extends SMART on FHIR to support clinical context synchronization between disparate, full featured healthcare applications which cannot be embedded within one another. This section defines the extensions on SMART On FHIR that allow for integration of FHIRcast with applications launched using SMART on FHIR.

Two launch scenarios are explicitly supported. The app is authorized to synchronize to a user’s session using the OAuth2.0 FHIRcast scopes.

During the OAuth2.0 handshake, the app requests and is granted one or more FHIRcast scopes. The EHR’s authorization server returns the hub url and any relevant session topics as SMART launch parameters.

The app requests one or more FHIRcast scopes, depending upon its needs to learn about specific workflow events or to direct the workflow itself.

Location: https://ehr/authorize?
            response_type=code&
            client_id=app-client-id&
            redirect_uri=https%3A%2F%2Fapp%2Fafter-auth&
            launch=xyz123&
            scope=fhircast%2FImagingStudy-open.read+launch+patient%2FObservation.read+patient%2FPatient.read+openid+profile&
            state=98wrghuwuogerg97&
            aud=https://ehr/fhir

Following the OAuth2.0 handshake, the authorization server returns the FHIRcast SMART launch parameters alongside the access_token.

{
  "access_token": "i8hweunweunweofiwweoijewiwe",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "patient/Observation.read patient/Patient.read",
  "state": "98wrghuwuogerg97",
  "intent": "client-ui-name",
  "patient":  "123",
  "encounter": "456",
  "hub.url" : "https://hub.example.com",
  "hub.topic": "2e5e1b95-5c7f-4884-b19a-0b058699318b"
  "hub.topic": "fdb2f928-5546-4f52-87a0-0648e9ded065"
}

The app then subscribes to the identified session

Two different launch scenarios are supported. For each launch scenario, the app discovers the session topic to which it subscribes.

EHR Launch: User SSO’s into app from EHR

The simplest launch scenario is the SMART on FHIR EHR launch, in which the subscribing app is launched from an EHR authenticated session. The app requests both the launch and desired FHIRcast scopes (for example, fhircast/ImagingStudy-open.read) and receives information about the user and session as part of the launch. The app subsequently subscribes to the launching user’s session.

In this scenario, the EHR authorizes the app to synchronize. The EHR provides a session topic as a SMART launch parameter which belongs to the EHR’s current user.

Standalone launch: User authenticates to EHR to authorize synchronization

This is an advanced scenario and is likely to not be widely supported. Implementer feedback is solicited.

If the app can’t be launched from the EHR, for example, it’s opening on a different machine, it may be able to use the standard SMART on FHIR standalone launch.

In this scenario, the user authorizes the app to synchronize to her session by authenticating to the EHR’s authorization server. The app requests desired FHIRcast scopes and the EHR provides a session topic as a SMART launch parameter which belongs to the EHR’s authorizing user.

Dynamic Registration for Native apps: Following SMART launch, parent client registers dynamic client which participates in FHIRcast session

This is an advanced scenario and is likely to not be widely supported. Implementer feedback is solicited.

Although dynamic registration for native apps is often appropriate from a security perspective, this technology is not widely implemented in healthcare. FHIRcast does not specify how the hub.topic and hub.url should be communicated to a dynamic client if and when its parent performed the SMART app launch. Generally, this will be the responsibility of the native app implementer in the absence of other guidance.

SMART Launch Example

An example of the launch parameters presented to the app during a SMART on FHIR launch is presented below.

{
  "access_token": "i8hweunweunweofiwweoijewiwe",
  "token_type": "bearer",
  "patient":  "123",
  "expires_in": 3600,
  "encounter": "456",
  "imagingstudy": "789",
  "hub.url" : "https://hub.example.com",
  "hub.topic": "fdb2f928-5546-4f52-87a0-0648e9ded065",
}

Note that the SMART launch parameters include the Hub’s base URL and the session identifier in the hub.url and hub.topic fields.

Alternate app launch

In practice, even enterprise apps are often launched from within a clinician’s workflow through a variety of bespoke web and desktop technologies. For example, an EHR might launch a desktop app on the same machine by specifying the executable on the Windows shell and passing contextual information as command line switches to the executable. Similarly, bespoke Microsoft COM APIs, shared polling of designated filesystem directories or web service ticketing APIs are also commonly used in production environments. The use of OAuth 2.0 strengthens and standardizes the security and interoperability of integrations. In the absence of OAuth 2.0 support, these alternate app launch mechanisms can also be used to share a session topic and therefore initiate a shared FHIRcast session.

A fictitious example Windows shell integration invokes a PACS system at system startup by passing some credentials, user identity and the FHIRcast session identifier (hub.topic) and hub base url (hub.url).

C:\Windows\System32\PACS.exe /credentials:<secured credentials> /user:jsmith /hub.url:https://hub.example.com /hub.topic:2e5e1b95-5c7f-4884-b19a-0b058699318b

An additional example is a simple (and relatively insecure) web application launch extended with the addition of hub.url and hub.topic query parameters.

GET https://app.example.com/launch.html?user=jsmith&hub.url=https%3A%2F%2Fhub.example.com&hub.topic=2e5e1b95-5c7f-4884-b19a-0b058699318b

Similarly, any bespoke app launch mechanism can establish a FHIRcast session by adding the hub.url and hub.topic parameters into the existing contextual information shared during the launch. Once launched, the app subscribes to the session and receives notifications following the standardized FHIRcast interactions.

No app launch

In a scenario in which the user manually starts two or more applications, the applications do not have the capability to establish a shared session topic. Since there’s no “app launch”, with its corresponding ability to exchange contextual information, the unique, unguessable, and session-specific hub.topic must be calculated by both the driving application’s hub and the subscribing application. The synchronizing application could use a shared algorithm and secret to generate the hub.topic.

A bespoke session topic generation algorithm could encrypt the current user’s username and a nonce with a shared secret to a pre-configured base url. In this contrived example, a base url and secret are securely configured on the subscribing app. The subscribing app generates and appends a nonce to the current user’s Active Directory username, encrypts that string with the shared secret according to an agreed upon encryption algorithm, and finally appends that encrypted string to the base url. The resulting url is unique to the current user and unguessable to a middle man due to the shared secret.

https://hub.example/com/AES256(username+nonce, shared secret)