On this page:
# Launch Context Scopes

Background: Mobile App and Patient Portal

In many cases an app wants to be authorized without knowing which patient it is expected to display.

For example, consider a 3rd party Mobile App that is authorizing itself against a hospital Patient Portal that acts as both a SMART on FHIR compliant Authorization Server and Resource Server. Users already have an account (with username and password) in the Patient Portal application, and by authorizing against those credentials the Mobile App can download data from the Patient Portal.

In this case the user is associated with a Patient resource ID on the Resource Server, but neither the Mobile App nor the user are aware of what resource ID that would be.

Background: Micro-Application Portal

Another use-case for launch scopes would be a portal which functions as a "desktop" of micro-applications (small web applications that do one thing, and do it well).

In this case, it could be assumed that the portal itself has a concept of which Patient (and/or which practitioner, which location, etc) is currently selected. The user's expectation would be that if a Patient is selected in the portal, any micro-apps would launch with the same Patient selected.

7.10Launch Scopes

 

SMART on FHIR specifies a set of scopes which request that the Authorization Server return the launch context to the Client.

From the Client's perspective, a flow using a launch scope works as follows:

  • The client performs an OAuth2 grant request (typically using the implicit or authorization code flows). In the initial authorize request, the client requests the launch/patient scope. This is a request for the Authorization Server to include a patient launch context.

http://myserver:9200/oauth/authorize?response_type=code&scope=openid+profile+launch/patient&client_id=my-client-id&state=af0ifjsldkj&redirect_uri=https://myapp.example.com/cb

  • At the end of the flow (several steps have been skipped here) when the access_token and id_token are received, the response will contain an additional claim called patient.
{
   "access_token":"eyJraWQiOiJ1bml0dGV (..snipped..)",
   "token_type":"bearer",
   "scope":"launch/patient openid profile",
   "id_token":"eyJraWQiOiJ1bml0dGVzdC1 (..snipped..)",
   "patient":"123"
}

7.10.1The OpenID and Profile Scopes

 

The openid and profile scopes are used by the Client to request user identity information from the Authorization Server as a part of the auth flow.

When these scopes are requested, an additional claim is returned by the authentication server called id_token. This claim is called the ID Token, and you can see it being returned in many of the examples above.

The ID Token is a Signed JWT. It may be decoded, revealing a number of attributes.

{
   "jti":"d34af0de-e65a-4c19-8e38-365916948356"
   "at_hash":"xDKTbwLJPrb6hr_loWD8Qw",
   "sub":"user123",
   "profile":"http:\/\/example.com\/issuer\/fhir\/RelatedPerson\/123",
   "iss":"http:\/\/example.com\/issuer",
   "nonce":"NONCETEXT-123",
   "aud":"my-client-id",
   "auth_time":1532416414,
   "exp":1532416474,
   "iat":1532416414,
   "name":"John Smith",
   "given_name":"John",
   "family_name":"Smith",
}