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.
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.
// 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"
}
}
Obtain authorization code
To obtain a token redirect the user to Aidbox /auth/authorize with following parameters:
Parameter
Description
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.
// Aidbox redirect back with code
http://smart-app-uri.com/redirect?
code=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0LXVzZXIiLCJleHAiOjE3MzQwMzMxMzksInNjb3BlIjpbImxhdW5jaC9wYXRpZW50Iiwib3BlbmlkIiwiZmhpclVzZXIiLCJvZmZsaW5lX2FjY2VzcyIsInBhdGllbnQvUGF0aWVudC5yZWFkIiwicGF0aWVudC9BbGxlcmd5SW50b2xlcmFuY2UucmVhZCIsInBhdGllbnQvQ2FyZVBsYW4ucmVhZCIsInBhdGllbnQvQ2FyZVRlYW0ucmVhZCIsInBhdGllbnQvQ29uZGl0aW9uLnJlYWQiLCJwYXRpZW50L0RldmljZS5yZWFkIiwicGF0aWVudC9EaWFnbm9zdGljUmVwb3J0LnJlYWQiLCJwYXRpZW50L0RvY3VtZW50UmVmZXJlbmNlLnJlYWQiLCJwYXRpZW50L0dvYWwucmVhZCIsInBhdGllbnQvRW5jb3VudGVyLnJlYWQiLCJwYXRpZW50L0ltbXVuaXphdGlvbi5yZWFkIiwicGF0aWVudC9NZWRpY2F0aW9uUmVxdWVzdC5yZWFkIiwicGF0aWVudC9PYnNlcnZhdGlvbi5yZWFkIiwicGF0aWVudC9Qcm9jZWR1cmUucmVhZCIsInBhdGllbnQvUHJvdmVuYW5jZS5yZWFkIiwicGF0aWVudC9QcmFjdGl0aW9uZXIucmVhZCIsInBhdGllbnQvT3JnYW5pemF0aW9uLnJlYWQiLCJwYXRpZW50L0xvY2F0aW9uLnJlYWQiXSwiYmFzZS11cmwiOiJodHRwczovL2cxMHRlc3QuZWRnZS5haWRib3guYXBwL2ZoaXIiLCJqdGkiOiIyWTNFbmxkSjV0M3lpbjN2TGxXTiIsImN0eCI6eyJwYXRpZW50IjoidGVzdC1wdC0xIn0sImNsaSI6ImluZmVybm8tcGF0aWVudC1zbWFydC1hcHAiLCJjb2RlX2NoYWxsZW5nZSI6IlZoNUlEXzdkdEEtTVlRTUtEdmNyZFJZN3dOSU9DWkdTSElUdlpCcU5yeDAiLCJvbi1iZWhhbGYiOnRydWUsImNvZGVfY2hhbGxlbmdlX21ldGhvZCI6IlMyNTYifQ.kyjOQ16BB_gieSKDcUjm9WpuzYtI1xRmVAMottiOOEw&
state=07864ab3-206a-495b-b8e9-2c66b7db6fc2
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:
Parameter
Description
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.
SMART App Launch using an External Identity Provider
Aidbox enables SMART App Launch with external identity providers. Set up an Identity Provider in Aidbox to sign in via the provider during the launch. Try it with our pre-configured demo (e.g., Keycloak):
