Receiving a SHOF launch
Requirements
The application created an
ActivityDefinition
.The user performing the launch must have an account on the shared IdP
Flow
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 theredirect_uri
. Note that thestate
(provided at the start of the/authorize
call) is returned to theredirect_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 asJWT
).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.
Authorize Request
GET
https://auth-service.koppeltaal.headease.nl/oauth2/authorize
The URL should be determined from the Koppeltaal metadata
Query Parameters
Name | Type | Description |
---|---|---|
aud* | string | URL of the Koppeltaal server (the same as the |
scope* | string | Always:
|
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
param) |
redirect_uri* | string | The URL to which the
should be returned |
client_id* | string | The |
response_type* | string | Altijd:
|
code_challenge* | String | A generated code challenge as per |
code_challenge_method* | String | Always:
|
Get Token
POST
https://authentication-service.koppeltaal.headease.nl/oauth2/token
The URL should be determined from the Koppeltaal metadata
Headers
Name | Type | Description |
---|---|---|
Content-Type* | String |
|
Request Body
Name | Type | Description |
---|---|---|
client_assertion* | String | JWT as composed for the SMART Backend Service for the application receiving the launch |
client_assertion_type* | String | Always:
|
redirect_uri* | string | The same
as used at the authorize request |
code* | string |
provided by the auth server on the redirect from the authorize request |
grant_type* | string | Always:
|
code_verifier* | String |
Topics
Last updated