Set up SMART on FHIR in Aidbox
This guide shows how to get set up SMART on FHIR in Aidbox
SMART on FHIR specifies authentication/authorization scheme for FHIR Applications. This scheme extends OAuth 2.0 and OpenID. To enable SMART on FHIR you need to create an Aidbox project and configure SMART API routes using the Aidbox API Constructor.
$ git clone https://github.com/Aidbox/aidbox-project-samples.git
In the
aidbox-project-samples/smart-on-fhir/core.edn
file you can see example of the API constructor configuration.Currently only two middlewares for SMART on FHIR authorization are implemented:
:smart.fhir/single-patient-auth-middleware
— Patient launch:smart.fhir/authorization-middleware
— Provider launch
To use SMART on FHIR you need to create a few resources like Client and AccessPolicies
POST /Client
Content-Type: text/yaml
Accept: text/yaml
resourceType: Client
id: smart-client
secret: some-secret
auth:
authorization_code:
redirect_uri: https://your/redirect/uri
refresh_token: true
secret_required: true
access_token_expiration: 36000
smart:
launch_uri: https://your/launch/uri
grant_types:
- authorization_code
The
launch_uri
parameter here specifies the launch URI for the EHR-based SMART App launch.You likely want to add some Access Policies to allow users see their data. Here we provide some examples for reference:
PUT /
Content-Type: text/yaml
Accept: text/yaml
# Allow patients to search resources linked with them
- resourceType: AccessPolicy
engine: matcho
matcho:
uri: '#/smart/.*'
params:
patient: .role.links.patient.id
roleName: patient
id: patient-smart
# Allow patients to read their info
- resourceType: AccessPolicy
engine: matcho
matcho:
uri: '#/smart/Patient/.*'
params:
id: .role.links.patient.id
roleName: patient
id: smart-patient-read
# Allow patients to read their info
- resourceType: AccessPolicy
engine: matcho
matcho:
uri: '#/smart/Patient'
params:
_id: .role.links.patient.id
roleName: patient
id: smart-patient-search-self
To generate SMART App launch URI use RPC API method
aidbox.smart/get-launch-uri
. The method accepts the following arguments:user
: id of theUser
resourceiss
: Aidbox base URLclient
: id of theClient
resourcectx
: additional launch contextоpatient
: id ofPatient
resourceencounter
: id ofEncounter
resourcefhirContext
: array of objects referring to any resource type other thanPatient
orEncounter
(see more details)

Standalone launch sequence
Authorization code flow with SMART on FHIR Standalone Launch:
- App requests SMART configuration from
base-url/.well-known/smart-configuration
- App requests FHIR conformance statement from
base-url/metadata
- App redirects to the EHR Authorization endpoint providing extra parameters:
scope
: OAuth scopes including scopes defined by SMART on FHIRaud
: FHIR Server base url
- Authorization server checks asks user to grant access to resources requested by the App and redirects to the App with code
- App exchanges code for token using the token endpoint
- App uses the token for resource access

EHR Launch Sequence
Authorization code flow with SMART on FHIR EHR Launch:
- App requests SMART configuration from
base-url/.well-known/smart-configuration
- App requests FHIR conformance statement from
base-url/metadata
- App redirects to the EHR Authorization endpoint providing extra parameters:
scope
: OAuth scopes including scopes defined by SMART on FHIRaud
: FHIR Server base url
- Authorization server checks asks user to grant access to resources requested by the App and redirects to the App with
code
- App exchanges
code
fortoken
using thetoken
endpoint - App uses the
token
for resource access
The result of the exchanging of the
code
for token
is a JSON object containing at least:access_token
. The access token issued by the authorization servertoken_type
. Fixed value:Bearer
scope
. Scope of access authorized
The SMART on FHIR sample in the Aidbox Project Samples is ready to pass the Inferno ONC Program and most of the Inferno Community SMART on FHIR tests. Follow the README in the Aidbox Project Samples repository to set up Aidbox for running these tests.
Last modified 2mo ago