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:
Register SMART Client
SMART defines two client (application) types: public
and confidential
. To determine the correct client type for you, ask: "Can my app protect a secret?"
If the answer is "Yes," use a confidential client.
Example: The app operates on a trusted server, ensuring that the secret is only accessed server-side.
Example: The app is a native application that employs additional technologies (such as dynamic client registration and universal redirect_uris) to secure the secret.
If the answer is "No," use a public client.
Example: The app is an HTML5 or JavaScript application running in a browser (including single-page applications), where the secret would be exposed in user space.
Example: The app is a native application that can only distribute a secret in a fixed, unprotected manner.
Client shall be Authorization Code Grant Client with several required values:
auth.authorization_code.token_format
Fixed value - jwt
auth.authorization_code.secret_required
true
- for confidential Client
false
- for public Client
smart.launch_uri
SMART Application launch endpoint
type
Fixed value - smart-app
secret
Only for confidential Client
Example
Create AccessPolicy
Launch App
SMART Launch Interaction Diagram:
Standalone launch
In SMART’s standalone launch flow, a user selects an app from outside the EHR (for example, by tapping an app icon on a mobile phone home screen).
The application should start launch by performing authorization code grant flow.
EHR launch
The EHR initiates a “launch sequence” by opening a new browser instance (or iframe) pointing to the app’s registered launch URL and passing some context.
Launch URL structure
Where:
smart-app-launch-endpoint
- SMART Application launch endpoint. It shall be equal toClient.smart.launch_uri
.iss
- Identifies the EHR's FHIR endpoint.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:
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:
Obtain authorization code
To obtain a token redirect the user to Aidbox /auth/authorize
with following parameters:
response_type
*
Fixed value - code
client_id
*
Client resource ID.
redirect_uri
*
Client's pre-registered redirect URIs. Must match the Client.auth.authorization_code.redirect_uri
value.
scope
*
String with scopes separated by space. Must describe the access that the app needs.
state
*
An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHALL be used for preventing cross-site request forgery or session fixation attacks. The app SHALL use an unpredictable value for the state parameter with at least 122 bits of entropy (e.g., a properly configured random uuid is suitable).
aud
*
URL of the EHR resource server from which the app wishes to retrieve FHIR data. Usually, it is <AIDBOX_BASE_URL>/fhir
.
code_challenge
This parameter is generated by the app and used for the code challenge, as specified by PKCE.
code_challenge_method
Fixed value - S256
launch
When using the EHR Launch flow, this must match the launch value received from the EHR (Aidbox). Omitted when using the Standalone Launch.
*- required parameter
Example
Obtain access token
After obtaining an authorization code, the app exchange the code for an access token. To do it send requiest to AIdbox's /auth/token
with following parameters:
grant_type
*
Fixed value - authorization_code
code
*
Code that the app received from Aidbox on the previous step.
redirect_uri
*
Client's pre-registered redirect URIs. Must match the Client.auth.authorization_code.redirect_uri
value.
code_verifier
This parameter is used to verify against the code_challenge
parameter previously provided in the authorize request.
client_id
Required for public apps
. Omit for confidential apps
.
*- required parameter
Example
Access FHIR API
Use access_token
received in the previous step to access Aidbox FHIR API:
Refresh access token
To refresh the access_token
send request to Aidbox's /auth/token
endpoint with following parameters:
grant_type
*
Fixed value - refresh_token
refresh_token
*
The refresh token from the authorization response.
client_id
Client resource ID.
scope
String with scopes separated by space. Must describe the access that the app needs.
*- required parameter