SMART on FHIR Integration
Overview
SMART on FHIR (Substitutable Medical Applications, Reusable Technologies) is an industry-standard OAuth 2.0-based authorization framework that enables EHR-initiated app launches. This allows clinicians to launch Lyrebird directly from their EHR (e.g., Cerner Millennium) with patient context automatically populated.
How It Works
Launch Flow
Step-by-Step Flow
1. EHR Launch: The EHR redirects to
/app/launch?launch=<token>&iss=<fhir-server-url>
2. Discovery: Lyrebird discovers OAuth endpoints from
{iss}/.well-known/smart-configuration3. Authorization: User is redirected to EHR's authorization endpoint with scopes
4. Callback: EHR redirects back to
/app/auth/smart/callback
5. Token Exchange: Lyrebird exchanges the code for:
- access_token - For FHIR API calls
- patient - Patient ID from launch context
- encounter - Encounter ID (if available)
- fhirUser - Practitioner reference (e.g., Practitioner/123)
6. App Launch: User lands on `/app` with patient context pre-populated
Endpoints
Launch Endpoint
GET /app/launch?launch=<token>&iss=<fhir-server-url>
Parameters:
- `launch` (required) - Launch token from EHR
- `iss` (required) - FHIR server base URL (issuer)
Flow:
1. Validates user is authenticated
2. Discovers SMART configuration from FHIR server
3. Generates OAuth state (stored in cookie for CSRF protection)
4. Redirects to EHR authorization endpoint
OAuth Callback
GET /api/auth/smart/callback?code=<auth-code>&state=<state>
Parameters:
- `code` (required) - Authorization code from EHR
- `state` (required) - State for CSRF validation
Flow:
1. Validates state matches cookie
2. Exchanges code for tokens
3. Saves SMART session to database
4. Creates EMR patient record for writeback
5. Redirects to `/app?smartLaunch=true&recordId=<id>`
Context Endpoint
GET /api/emr/smart-context/<recordId>
Returns patient context for a SMART launch record. Called by frontend after redirect.
Response:
{
"recordId": "uuid",
"patientId": "fhir-patient-id",
"patientName": "John Smith",
"patientGender": "MALE",
"encounterId": "fhir-encounter-id",
"practitionerId": "fhir-practitioner-id",
"integration": {
"id": "uuid",
"integration": "fhir",
"displayName": "SMART on FHIR"
}
}
Configuration
EHR Registration
The app must be registered with the EHR as a SMART client. Registration provides:
- Client ID
- Client Secret (optional)
Scopes Requested
launch openid fhirUser patient/Patient.read patient/Encounter.read