Stream: smart
Topic: Launch Context
Grahame Grieve (May 14 2020 at 01:02):
@Josh Mandel I'm having trouble reading the smart app launch around context.
This is what I think it says:
- Apps that launch from the EHR will be passed an explicit URL parameter called
launch - if you access to the launch scope, you provide a scope of
launch, or elselaunch/patientorlaunch/patient - except I don't know what that means - there's only one launch scope. So what does it mean to qualify the scope?
- the client echoes the launch scope back
- why? What happens if it changes it? is that an error? It must be... which means that the server remembers it... so why echo it?
- then, the server provides the launch context back with the access token
- only now, it's not called
launch, it's now migrated to being calledpatientorencounter, though it's not clear to me quite where those are defined or come from... i can only suppose that they come from the server's secret knowledge, making me wonder why there's a launch parameter in the first place...?
Josh Mandel (May 14 2020 at 01:34):
Let's take these one by one...
Josh Mandel (May 14 2020 at 01:35):
if you access to the launch scope, you provide a scope of launch, or else launch/patient or launch/patient
For the SMART EHR Launch Flow, you include launch scope to indicate that you need to learn launch context, and you include a launch query parameter to tie the session together in a way the EHR can control.
Josh Mandel (May 14 2020 at 01:36):
except I don't know what that means - there's only one launch scope. So what does it mean to qualify the scope?
The "qualifications" like launch/patient are used in the SMART Standalone Launch flow, for an app to say to the EHR: "please make sure you figure out what patient record I should be working with before completing the launch process -- that's your job, not mine"
Josh Mandel (May 14 2020 at 01:38):
the client echoes the launch scope back why? What happens if it changes it? is that an error? It must be... which means that the server remembers it... so why echo it?
Here we're back to talking about the SMART EHR Launch flow: thelaunch URL parameter is an opaque handle to the launch context; it's something the EHR knows how to interpret and the app does not. This allows for apps launched across browsers, or popping a system browser open from a native EHR client (etc), and the launch URL parameter ties the session together. The EHR needs to validate and resolve the launch value into a launch context, but it doesn't know a priori which launch value to expect with any given incoming request to the authorize? endpoint. The EHR relies on the app to provide this parameter this as a means of tying the session together.
Josh Mandel (May 14 2020 at 01:41):
only now, it's not called launch, it's now migrated to being called patient or encounter,
Well, launch and launch/patient and launch/encounter are scopes which, if granted, will cause the app to learn information (conveyed in the access token response as JSON properties like patient and encounter). They're not so much "migrating" as "here's how you ask for something, and here's what you get". The "what you get" properties are defined at http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context/index.html#launch-context-arrives-with-your-access_token. We might look for stronger naming convention, but "launch/patient" -> "patient" and "launch/encoutner" -> "encounter" seemed fairly transparent to me.
Josh Mandel (May 14 2020 at 01:41):
I feel like I haven't told you anything new here, though @Grahame Grieve, since I think you've implemented all of this already, years ago -- so I may be missing the key aspect behind some of your questions.
Grahame Grieve (May 14 2020 at 02:24):
it turned out that there was something I had not implemented
Grahame Grieve (May 14 2020 at 02:26):
is it reasonable for a client to expect that it it specifies launch/patient, then the access_token answer will contain a patient? is that the expectation? I don't see it stated anywhere explicitly
Michele Mottini (May 14 2020 at 03:42):
... that's how patient apps normally work - specify launch/patient, get back the patient ID
Grahame Grieve (May 14 2020 at 03:48):
yep - but is it explicitly mandatory? seems it should be stated. Does anyone know if other launch contexts than patient and encounter are supported? Is it expected that the access_token response includes patient if it has encounter?
Lloyd McKenzie (May 14 2020 at 04:13):
Encounters could be associated with multiple patients (even if that's not supported in core)
Lloyd McKenzie (May 14 2020 at 04:13):
(Well it is indirectly - via Group)
Josh Mandel (May 14 2020 at 13:49):
In general in OAuth, scopes are negotiable. A client can ask for certain scopes and a user or authorization server can grant a subset or even a different set. We do have conformance language that allows a server to say whether it supports patient context or encounter context as a capability.
Josh Mandel (May 14 2020 at 13:49):
That falls under the SMART core capability discovery page.
Grahame Grieve (May 14 2020 at 18:24):
so I am asking about the contexts, not the scopes. It seems the language is weak around the contexts
Robert Scanlon (May 14 2020 at 19:41):
I agree it would be great if the language was more direct about requirements, but I think it at least sets the expectation that a client will receive a patient in the token response when requesting launch/patient (and same for encounter and launch/encounter): "Once an app is authorized, the token response will include any context data the app requested – along with (potentially!) any unsolicited context data the EHR decides to communicate."
Robert Scanlon (May 14 2020 at 19:42):
Good question if you need to request both if you are expecting both a patient and encounter. Or if that is even possible.
Josh Mandel (May 14 2020 at 21:07):
It seems the language is weak around the contexts
Would be happy to accept suggestions on how to tighten -- PR preferred (and we're working on conformance language in Argonaut, so we can review / merge pretty quickly).
Brian Postlethwaite (Jun 29 2020 at 12:09):
I'm facing this one today around having multiple patients in context. Should this be a space or comma sepeated list (as is a json prop can't repeat)
Josh Mandel (Jun 29 2020 at 13:05):
There's no feature in SMART to list multiple patients in an authorization context today. We have user-level context which shares sccess for the whole set of patients available to the authorizing user. but if you want to provide access to, say, three specific patients, you would need to get three patient-specific access tokens, with today's SMART App Launch spec.
Josh Mandel (Jun 29 2020 at 13:06):
This is a good subject for discussion at tomorrow's Meetup (details in #Security and Privacy ).
Emil Diaz (Jan 22 2021 at 00:48):
@Josh Mandel how would you interpret the following combination of scopes user/*.read + launch/patient? I'm trying to reconcile the clarification you provided above, that the user-level context is for ALL patients available to that user, with possibility that the app may also request a specific patient launch context in the same auth session.
Josh Mandel (Jan 22 2021 at 00:51):
"I want access to read all the data that you can read, and I want to know what patient you had open in the EHR when you launched me"
- "I" == app
- "You" == user running the app
Josh Mandel (Jan 22 2021 at 00:51):
(Or for standalone launch, the latter part becomes "what patient do you selected in the picker when you launched me", but this is a less common case.)
Emil Diaz (Jan 22 2021 at 01:43):
Ah, much clearer now. Thanks for the clarification @Josh Mandel
Brian Postlethwaite (Jul 20 2021 at 04:16):
Currently we have the profile value in the id_token (can't find where we document that or have examples) and that is the full URL for the user:
https://example.org/fhir/Practitioner/45
https://example.org/fhir/Patient/123
https://example.org/fhir/Person/123
https://example.org/fhir/RelatedPerson/123
I'm wondering do we have anything anywhere defining where a PractitionerRole could be defined as context?
Currently I've drafted to either have them as extra claims in the id_token
(practitioner, practitionerRole, organization)
and alternatively in the launch context arriving with the access token.
My preference is to want them in the id_token as that's what I'm using for my internal authorization tasks to ensure that the practitioner has the correct rights in the Smart App based on the role that they are in with the organization
Josh Mandel (Jul 20 2021 at 13:29):
If you want to communicate additional authentication relevant information to the app, I'd indeed look at putting this in the id_token. It's outside of the SMART spec, but it's certainly fair game.
Robert Scanlon (Jul 20 2021 at 18:48):
Minor point, but should it be fhirUser and not profile here: "Currently we have the profile value in the id_token"?
Josh Mandel (Jul 20 2021 at 19:07):
It should! (I was assuming Brian had some good reason for using profile, and since they're extending SMART in various ways, interop is less of a consideration.)
Brian Postlethwaite (Jul 20 2021 at 23:06):
Is that what's expected in the id_token too? I thought it was just the scope, it the claim.
Brian Postlethwaite (Jul 20 2021 at 23:06):
Hence why was wondering where the id_token is documented (in smart)
Josh Mandel (Jul 20 2021 at 23:59):
Claims: The EHR SHALL support the inclusion of SMART’s fhirUser claim within the id_token issued for any requests that grant the openid and fhirUser scopes
Last updated: Apr 12 2022 at 19:14 UTC
