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 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:
1. an id_token (contains information of the logged in user as JWT).
2. A no-op access_token (not to be used on the Koppeltaal Server because it is user-specific).
3. 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

Name	Type	Description
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 `launch`param)
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*	String	A generated code challenge as per rfc7636
code_challenge_method*	String	Always: `S256`

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*

String

A generated code challenge as per rfc7636

code_challenge_method*

String

Always:

S256

The Location header will redirect with a code and the state

Location: https://launch-testsuite.koppeltaal.headease.nl/module_authentication_shof?code=05b542e2-6206-449b-924b-99d39168029b&state=99a8cf9a-28c2-4867-8123-486c04003482

Get Token

POST https://authentication-service.koppeltaal.headease.nl/oauth2/token

The URL should be determined from the Koppeltaal metadata

Headers

Name Type Description

Name	Type	Description
Content-Type*	String	`application/x-www-form-urlencoded`

Content-Type*

String

application/x-www-form-urlencoded

Request Body

Name Type Description

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: `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 rfc7636

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

rfc7636

The OIDC response plus additional context fields used in the launch is returned

{
  "access_token": "NOOP",
  "id_token": "eyJraWQiOiJvUDQ4NmxJcmwzRFFQdXF0dVVqUmxqc01oWFA0alJmdXoxS19uX0dpQmRrIiwiYWxnIjoiUlM1MTIiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLXNlcnZpY2Uua29wcGVsdGFhbC5oZWFkZWFzZS5ubC8iLCJhdWQiOiJiMDJkNmVhNi1iMWEyLTRjZDQtODJmNS1iNjQyM2Q2NmE5ODgiLCJuYmYiOjE2MzI4MTMzNTAsImV4cCI6MTYzMjgxNjk1MCwibm9uY2UiOiJmNGMxODZlNy1jMzI2LTQxODAtYjFmMi1jYTllMWI4YTgyYWQiLCJzdWIiOiJQYXRpZW50LzE5NjMiLCJhenAiOiJiMDJkNmVhNi1iMWEyLTRjZDQtODJmNS1iNjQyM2Q2NmE5ODgifQ.UfBtTACLOhsCMr4Tlen3RUFek06WgWc-aaTPQzJzmHVGYBLY3CnJXTLI1FfCzp1ChM3vx-e2jbFCDHak6ennsuitki-1HnrZitTKpG8qKZK_f24gwVFM5LmzdUXtuTszJSeulpRG8zmNI96pqaIW4ru995LwhKLd-XSOY02BbAMo4XZ46ZW8DBXnhr32CI9TUza8NEQoxlQAF8EboUhro5vauPrjdshP3jQFUNSs5NceB4er3RnF10Zd6SiLFP-_c2ynaj_v87fJEgVGw63byYcKm6O3bTW2KsSz_YNYDYv8DWjYAp25P79e-Hlc3ERcybhLnLy0_-Rkvjk5P_240g"
  "scope": "openid fhirUser launch",
  "token_type": "Bearer",
  "expires_in": "3600",
  "resource": "Task/37fa63e3-b118-4180-8470-74b1df508bf6",
  "definition": "https://fhir-server.koppeltaal.headease.nl/fhir/DEFAULT/ActivityDefinition/fbbf47a5-2a55-4e3a-8dec-a8eb63875374",
  "sub": "Practitioner/52b6535b-4e69-455b-9d9f-952e708ad393",
  "patient": "Patient/70184602-4d15-4ca9-89a6-00e78123b22e",
  "intent": "plan"
}

Topics

TOP-KT-007 - Koppeltaal Launch

PreviousToken introspection NextDetailed technical guidance

Last updated 2 months ago