SMART App Launch
Last updated
Was this helpful?
Last updated
Was this helpful?
Performing with Aidbox requires:
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 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
SMART Launch Interaction Diagram:
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 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.
Where:
smart-app-launch-endpoint - SMART Application launch endpoint. It shall be equal to Client.smart.launch_uri.
iss - Identifies the EHR's FHIR endpoint.
launch parameter JWT shall contain the following claims:
client *
valueString
user*
valueString
Aidbox user ID.
exp*
valueInteger
Experation time in seconds
ctx.patient*
valueString
Patient ID
* - required claim
Aidbox provides an endpoint to build the correct launch URI:
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
code_challenge_method
Fixed value - S256
launch
*- required parameter
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
Use access_token received in the previous step to access Aidbox FHIR API:
To refresh the access_token send request to Aidbox's /auth/token endpoint with following parameters:
grant_type *
Fixed value - refresh_token
refresh_token *
client_id
Client resource ID.
scope
String with scopes separated by space. Must describe the access that the app needs.
*- required parameter
The application should start launch by performing .
launch - JWT identifier for this specific launch and context associated with it. It shall be signed with an .
Aidbox ID.
This parameter is generated by the app and used for the code challenge, as specified by .
When using the , this must match the launch value received from the EHR (Aidbox). Omitted when using the .
The refresh token from the .
Aidbox enables SMART App Launch with external identity providers. Set up an in Aidbox to sign in via the provider during the launch. Try it with our pre-configured demo (e.g., Keycloak):
