Implementer guidance

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

Security Considerations

FHIRcast enables the synchronization of healthcare applications user interfaces in real-time through the exchange of a workflow event to a small number of disparate applications. The notification message which describes the workflow event is a simple json wrapper around one or more FHIR resources. These FHIR resources can contain Protected Health Information (PHI).

Actors

  • Subscribing app
  • Hub
  • Authorization Server
  • Resource server

FHIRcast ties SMART as the authnz layer together with WebSub for subscription and event notification.

Sources of Risk

  1. The FHIRcast Hub pushes PHI to a dynamic url specified by the authenticated app.
  2. An app's credentials or a Hub's lack of authentication could be used by a malicious system to control the user's session.
  3. FHIRcast recommends the use of SMART on FHIR, but does not require it. Implementation-specific launch, authentication, and authorization protocols may be possible. These alternate protocols should be scrutinized by implementers for additional security risks.

SMART on FHIR

SMART on FHIR profiles OAuth 2.0's authorization code grant type and extends it by introducing an "EHR Launch Sequence". The Argonaut Project performed a formal security review of SMART on FHIR, resulting in a Risk Assessment report.

FHIRcast builds on SMART by introducing a new syntax for standard OAuth 2.0 scopes, as well as two new SMART launch parameters of hub.url and hub.topic.

HTTP Web Hooks using WebSub

WebSub is a W3C RFC designed for the distribution of web content through a standardized web hooks architecture. FHIRcast uses WebSub to allow clients to subscribe and unsubscribe to the Hub and, for the Hub to notify subscribers of events.

Unlike WebSub, FHIRcast requires that both the Hub and the subscribing apps endpoints are exposed over https.

The below flow diagram illustrates each of the interactions.

FHIRcast flow diagram

How does the subscriber authenticate to the Hub?

The subscribing app can make three distinct API calls to the Hub. For each of these calls, the subscribing app authenticates to the Hub with the Hub's authorization server issued SMART access_token. Per SMART on FHIR, this access_token is presented to the Hub in the HTTP Authorization header.

  1. App subscribes to Hub
  2. App requests change to shared context
  3. App unsubscribes from session
POST https://hub.example.com
Host: hub.example.com
Authorization: Bearer i8hweunweunweofiwweoijewiwe

How does the Hub validate the subscriber?

The Hub can make three distinct API calls to the subscribing app's hub.callback url.

  1. Hub verifies callback url with app
  2. Hub notifies app of event
  3. Hub denies subscription

This flow diagram describes the actors and actions.

WebSub security flow

The subscribing app initiates the FHIRcast subscription, authenticating to the Hub with its bearer token, and providing the hub.secret and hub.callback url. The Hub verifies intent and ownership by performing an HTTP GET to the hub.callback url, with a hub.challenge. The subscribing app must echo the hub.challenge in the body of an HTTP 202 response. Once a workflow event occurs, the Hub notifies the app of the event by POSTing to the subscribing app's hub.callback url. The Hub provides an HMAC signature of the previously provided hub.secret in the X-Hub-Signature HTTP header.

POST https://app.example.com/session/callback/v7tfwuk17a HTTP/1.1
Host: subscriber
X-Hub-Signature: sha256=dce85dc8dfde2426079063ad413268ac72dcf845f9f923193285e693be6ff3ae

The client that creates the subscription may not be the same system as the server hosting the callback url. (For example, some type of federated authorization model could possibly exist between these two systems.) However, in FHIRcast, the Hub assumes that the same authorization and access rights apply to both the subscribing client and the callback url.

WebSub Security Considerations

The WebSub RFC defines specific security considerations, including the below, which are listed here for emphasis or elevation from optional to mandatory. * Subscribers must communicate with a Hub over https. * Hub must reject unsecured http callback urls. * The subscribing app's hub.callback url should be unique and unguessable. * Subscribing apps must provide a hub.secret and validate the X-Hub-Signature in the notification message. * Hubs must reject subscriptions if the callback url does not echo the hub.challenge as part of the intent verification GET. * When computing the HMAC digest with the hub.secret for the X-Hub-Signature HTTP header, Hubs must use SHA-256 or greater and must not use SHA-1. * For each subscription, the hub.secret must be unique, unguessable and securely stored by both the Hub and the app. * To prevent a subscriber from continuing to receive information after its authorization has ended, if using OAuth 2.0, the Hub must limit the subscription's lease_seconds to be less than or equal to the access token's expiration timestamp.

Experimental Websockets support

In addition to the web hooks communication pattern, the FHIRcast community is experimenting with the use of websockets for event notification. Below are some incomplete considerations for a potential websockets implementation.

Subscribers SHOULD only use and Hub's SHOULD only accept connections made over the secure wss:// websocket protocol and not the unsecured ws:// websocket protocol.

The WebSockets standard defines an Origin header, sent from the client to the server and intended to contain the url of the client. Subscribers using websockets may be running in a browser, in which case the browser enforces origin reporting to the Hub, or native apps in which the origin reported to the Hub can not be trusted. Therefore, a Hub exposing a websocket connection MUST not rely upon the origin sent by the subscriber.

While native app subscribers can send any standard HTTP headers, notably including Authorization: Bearer, browser-based subscribers are limited to only HTTP Basic Auth or cookies. Therefore, the typical use of the OAuth 2.0 access_token for bearer authentication does not consistently work with websockets. FHIRcast describes a "ticket"-based authentication system, in which the hub.topic provided to the subscriber as part of the secured SMART app launch serves not only as a unique session identifier, but also as an "authorization ticket". This authorization ticket effectively acts as a bearer token. The Hub should therefore take care to generate opaque and unique hub.topic values.