Receiving a SHOF launch

Requirements

1. The application created an ActivityDefinition.

2. The user performing the launch must have an account on the shared IdP

Flow

SMART HTI Flow

1. When the launch arrives, the conformance is retrieved from the Koppeltaal Server. Here the authorize & token URL can be requested.

2. 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.

3. 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.

4. 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
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	Altijd: code
code_challenge*	String	A generated code challenge as per rfc7636
code_challenge_method*	String	Always: S256

302 The Location header will redirect with a code and the state

Loocation: 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
Content-Type*	String	application/x-www-form-urlencoded

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

200 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"
}

401: Unauthorized Client unauthorized or wrong code_verifier

{
    // Response
}

Topics

TOP-KT-007 - Koppeltaal Launch