Receiving a SHOF launch
Last updated
Last updated
The application created an ActivityDefinition.
The user performing the launch must have an account on the shared IdP
When the launch arrives, the conformance is retrieved from the Koppeltaal Server. Here the authorize & token URL can be requested.
A redirect is sent to the authorize URL. The auth server will redirect the browser to a shared IdP using an OIDC code flow. If the launching platform does not use this shared IdP as a login mechanism, the user will have to login here as well. At the POC it is possible to create an account directly from this login screen. New users are given the role patient by default. The authorize call will check if the logged in user matches the user from the launch token.
A successful authorize call returns the code & state parameters to the redirect_uri. Note that the state (provided at the start of the /authorize call) is returned to the redirect_uri, this way you can find out which launch request is involved and, for example, relate to a specific user session.
From the back-end, execute the Get Token request. Here, the code is exchanged for:
an id_token (contains information of the logged in user as JWT).
A no-op access_token (not to be used on the Koppeltaal Server because it is user-specific).
Additional context fields such as task, which the auth server fills based on the JWT provided as launch param.
By means of the context object it can be determined who, with which role, is logged on to the system and which task should be opened. When there is a valid response to this request, the user can be authenticated and e.g. a session can be created for the user.
GET https://auth-service.koppeltaal.headease.nl/oauth2/authorize
The URL should be determined from the Koppeltaal metadata
aud*
string
URL of the Koppeltaal server (the same as the iss value)
scope*
string
Always:
launch openid fhirUser
state*
string
An opaque value used by the client to maintain the state between the request and the callback. The authorization server takes this value when redirecting the user agent back to the client. The parameter MUST be used to prevent cross-site request forgery (CSRF) attacks or session fixation
launch*
string
The HTI token (from the launchparam)
redirect_uri*
string
The URL to which the
code
should be returned
client_id*
string
The client_id (from Domain Admin) of the application receiving the launch
response_type*
string
Always:
code
code_challenge_method*
String
Always:
S256
The Location header will redirect with a code and the state
POST https://authentication-service.koppeltaal.headease.nl/oauth2/token
The URL should be determined from the Koppeltaal metadata
Content-Type*
String
application/x-www-form-urlencoded
client_assertion*
String
JWT as composed for the
SMART Backend Service for the application receiving the launch
client_assertion_type*
String
Always:
urn:ietf:params:oauth:client-assertion-type:jwt-bearer
redirect_uri*
string
The same redirect_uri as used at the authorize request
code*
string
code provided by the auth server on the redirect from the authorize request
grant_type*
string
Always:
authorization_code
code_verifier*
String
Unhashed value used foe generating the code_challenge in the authorize step as per
The OIDC response plus additional context fields used in the launch is returned
