SMART App Launch

This functionality is available starting from version 2411. The FHIR Schema Validator Engine should be enabled.

Performing SMART App Launch with Aidbox requires:

1. Client for SMART Application

It shall be Authorization Code Grant Client with several required values:

Client resource field	Description
auth.authorization_code.token_format	Fixed value - jwt
smart.launch_uri	SMART Application launch endpoint
type	Fixed value - smart-app

Example

PUT /Client/my-smart-app-client-id
content-type: application/json
accept: application/json

{
  "resourceType": "Client",
  "id": "my-smart-app-client-id",
  "auth": {
    "authorization_code": {
      "redirect_uri": "http://smart-app-uri.com/",
      "refresh_token": true,
      // always shall be jwt
      "token_format": "jwt",
      "access_token_expiration": 3600000
    }
  },
  // always shall have smart.launch_uri value
  "smart": {
    "launch_uri": "http://smart-app-launch-endpoint/launch.html"
  },
  // always shall be "smart-app" type
  "type": "smart-app",
  "secret": "quOfCRS7ty1RMUQq",
  "grant_types": [
    "code"
  ]
}

2. Launch URI

Launch URI structure:

http://smart-app-launch-endpoint?iss=<fhir-endpoint>&launch=<opaque-identifier>

Where:

1. smart-app-launch-endpoint - SMART Application launch endpoint. It shall be equal to Client.smart.launch_uri.

2. iss - Identifies the EHR's FHIR endpoint.

3. launch - JWT identifier for this specific launch and context associated with it. It shall be signed with an Aidbox private key.

launch parameter JWT shall contain the following claims:

Claim name	Value type	Description
client *	valueString	Aidbox client ID.
user*	valueString	Aidbox user ID.
exp*	valueInteger	Experation time in seconds
ctx.patient*	valueString	Patient ID

* - required claim

Get launch URI endpoint

Aidbox provides an endpoint to build the correct launch URI:

Request

POST /rpc
content-type: application/json
accept: application/json

{
  "method": "aidbox.smart/get-launch-uri",
  "params": {
    "user": "my-aidbox-user-id",
    "iss": "https://example.edge.aidbox.app/fhir",
    "client": "my-smart-app-client-id",
    "ctx": {
      "patient": "my-patient-id"
    }
  }
}

Response

// 200 OK

{
 "result": {
  // Run this uri to perform SMART App Launch
  "uri": "http://smart-app-launch-endpoint/launch.html?iss=https://example.edge.aidbox.app/fhir&launch=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQiOiJteS1zbWFydC1hcHAtY2xpZW50LWlkIiwidXNlciI6Im15LWFpZGJveC11c2VyLWlkIiwiZXhwIjoxNzMzMzk5Nzk3LCJjdHgiOnsicGF0aWVudCI6Im15LXBhdGllbnQtaWQifX0.wn78VQrDN8xmS_wowQ-a3MRPuOEhFZ-PyTMn5BHe5No",
  "launch": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQiOiJteS1zbWFydC1hcHAtY2xpZW50LWlkIiwidXNlciI6Im15LWFpZGJveC11c2VyLWlkIiwiZXhwIjoxNzMzMzk5Nzk3LCJjdHgiOnsicGF0aWVudCI6Im15LXBhdGllbnQtaWQifX0.wn78VQrDN8xmS_wowQ-a3MRPuOEhFZ-PyTMn5BHe5No",
  "iss": "https://example.edge.aidbox.app/fhir",
  "launch-uri": "http://smart-app-launch-endpoint/launch.html"
 }
}

External Identity Provider

Aidbox supports SMART App Launch with external identity provider authorization. In this case, an Identity Provider needs to be set up in Aidbox then you will be able to Sign In with the external identity provider during the SMART App Launch flow.

Try SMART App Launch using Aidbox and an external identity provider (Keycloak) running our pre-configured demo:

Example: SMART App Launch using Aidbox and Keycloak