FHIR Chat · fhircast-docs / Issue #299 websocket - how does subscribe... · fhircast-github

Stream: fhircast-github

Topic: fhircast-docs / Issue #299 websocket - how does subscribe...

Github Notifications (FHIRcast) (Nov 15 2019 at 03:36):

isaacvetter opened Issue #299:

When a subscriber initially requests a subscription, it performs an HTTP POST, like so:

POST https://hub.example.com
Content-Type: application/x-www-form-urlencoded

hub.mode=subscribe&hub.events=patient-open,patient-close&hub.lease_seconds=3600&hub.topic=fdb2f928-5546-4f52-87a0-0648e9ded065&hub.secret=shhh-this-is-a-secret&hub.callback=https://myapp.com

The hub.events and hub.lease_seconds parameters are evaluated by the Hub, and the Hub responds, in the "Intent Verification" exchange with the actual hub.events and hub.lease_seconds for the newly created subscription.

There's a few reasons for the Hub's ability to override a subscriber's requests content or length of a requested subscription:

1. _authorization_: a subscriber mustn't be able to subscribe to events for which it's not authorized. It's the Hub's responsibility to ensure that a subscription is limited to, not only, the subscriber's authorized events, but also the length of the subscription mustn't overrun the lifetime of the authorization.
2. _mere capability_: the hub.events list of events supplied by the subscriber asks the Hub: hey Hub! do you support these events? In some cases, the answer may be no. Ultimately, for webhooks, the Hub commits to sending specific event notifications in the "Intent Verification" exchange

This all makes sense in hub.channel.type=webhook, but, hub.channel.type=websockets` currently doesn't include the "Intent Verification" exchange. How does the Hub communicate approved authorization or it's support for the requested events in a websocket subscription?

Github Notifications (FHIRcast) (Nov 15 2019 at 03:46):

isaacvetter edited Issue #299:

When a subscriber initially requests a subscription, it performs an HTTP POST, like so:

POST https://hub.example.com
Content-Type: application/x-www-form-urlencoded

hub.mode=subscribe&hub.events=patient-open,patient-close&hub.lease_seconds=3600&hub.topic=fdb2f928-5546-4f52-87a0-0648e9ded065&hub.secret=shhh-this-is-a-secret&hub.callback=https://myapp.com

The hub.events and hub.lease_seconds parameters are evaluated by the Hub, and the Hub responds, in the "Intent Verification" exchange with the actual hub.events and hub.lease_seconds for the newly created subscription.

There's a few reasons for the Hub's ability to override a subscriber's requests content or length of a requested subscription:

1. _authorization_: a subscriber mustn't be able to subscribe to events for which it's not authorized. It's the Hub's responsibility to ensure that a subscription is limited to, not only, the subscriber's authorized events, but also the length of the subscription mustn't overrun the lifetime of the authorization.
2. _mere capability_: the hub.events list of events supplied by the subscriber asks the Hub: hey Hub! do you support these events? In some cases, the answer may be no. Ultimately, for webhooks, the Hub commits to sending specific event notifications in the "Intent Verification" exchange

This all makes sense in hub.channel.type=webhook, but, hub.channel.type=websockets` currently doesn't include the "Intent Verification" exchange. How does the Hub communicate approved authorization or its support for the requested events in a websocket subscription?

Github Notifications (FHIRcast) (Nov 15 2019 at 03:51):

isaacvetter edited Issue #299:

When a subscriber initially requests a subscription, it performs an HTTP POST, like so:

POST https://hub.example.com
Content-Type: application/x-www-form-urlencoded

hub.mode=subscribe&hub.events=patient-open,patient-close&hub.lease_seconds=3600&hub.topic=fdb2f928-5546-4f52-87a0-0648e9ded065&hub.secret=shhh-this-is-a-secret&hub.callback=https://myapp.com

The hub.events and hub.lease_seconds parameters are evaluated by the Hub, and the Hub responds, in the "Intent Verification" exchange with the actual hub.events and hub.lease_seconds for the newly created subscription.

There's a few reasons for the Hub's ability to override a subscriber's requests content or length of a requested subscription:

1. _authorization_: a subscriber mustn't be able to subscribe to events for which it's not authorized. It's the Hub's responsibility to ensure that a subscription is limited to, not only, the subscriber's authorized events, but also the length of the subscription mustn't overrun the lifetime of the authorization.
2. _mere capability_: the hub.events list of events supplied by the subscriber asks the Hub: hey Hub! do you support these events? In some cases, the answer may be no. Ultimately, for webhooks, the Hub commits to sending specific event notifications in the "Intent Verification" exchange

This all makes sense in hub.channel.type=webhook, but, hub.channel.type=websockets currently doesn't include the "Intent Verification" exchange. How does the Hub communicate approved authorization or its support for the requested events in a websocket subscription?

Github Notifications (FHIRcast) (Nov 15 2019 at 04:14):

isaacvetter commented on Issue #299:

Although the "Intent Verification" step using webook is primarily intended to confirm ownership of the callback url, it also serves as confirmation of the subscription. This confirmation is similarly needed for websocket.

We could minimally provide this subscription confirmation by mirroring the "Intent Verification" request over websocket, like so:

websocket Subscription Confirmation

To confirm a subscription request, upon the subscriber establishing a websocket connection to the hub.channel.endpoint wss url, the Hub SHALL send a confirmation. This confirmation includes the following elements:

Field	Optionality	Type	Description
hub.mode	Required	string	The literal string "subscribe".
hub.topic	Required	string	The session topic given in the corresponding subscription request.
hub.events	Required	string	A comma-separated list of events from the Event Catalog corresponding to the events string given in the corresponding subscription request.
hub.lease_seconds	Required	number	The Hub-determined number of seconds that the subscription will stay active before expiring, measured from the time the verification request was made from the Hub to the subscriber. If provided to the client, the Hub SHALL unsubscribe the client once lease_seconds has expired and MAY send a subscription denial. If the subscriber wishes to continue the subscription it MAY resubscribe.

websocket Intent Verification Request Example

{
  "hub.mode": "subscribe",
  "hub.topic": "fdb2f928-5546-4f52-87a0-0648e9ded065",
  "hub.events": "patient-open,patient-close",
  "hub.lease-seconds": 7200
}
~~~

Last updated: Apr 12 2022 at 19:14 UTC