1. SMART on FHIR Overview
SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR is a framework that allows third-party medical applications to securely integrate with EHR/EMR via OAuth 2.0 + FHIR.
┌─────────────┐ ┌─────────────┐
│ SMART App │ OAuth 2.0 flow │ EHR/EMR │
│ (web/ │ ◀────────────────▶ │ (FHIR │
│ mobile) │ FHIR API calls │ Server) │
└─────────────┘ └─────────────┘
│ │
│ ┌──────────────┐ │
└───────▶│ Auth Server │◀─────────┘
│ (OAuth 2.0) │
└──────────────┘
2. Launch Types
EHR Launch
App is opened from within the EHR — EHR transmits context (patient, encounter).
1. Bác sĩ click "Open App" trong EHR
2. EHR redirect → App với launch parameter
3. App → Authorization Server (authorize endpoint)
4. User đồng ý → Auth Server trả code
5. App đổi code → access_token + id_token
6. App gọi FHIR API với access_token
GET https://smart-app.example.com/launch
?iss=https://fhir-server.hospital.vn/fhir/r5
&launch=xyz123
Standalone Launch
App runs independent, find the FHIR server yourself and ask for permission.
GET https://fhir-server.hospital.vn/fhir/r5/.well-known/smart-configuration
{
"authorization_endpoint": "https://auth.hospital.vn/authorize",
"token_endpoint": "https://auth.hospital.vn/token",
"capabilities": [
"launch-ehr",
"launch-standalone",
"client-public",
"client-confidential-symmetric",
"sso-openid-connect",
"context-ehr-patient",
"permission-v2"
],
"scopes_supported": [
"openid",
"fhirUser",
"launch",
"launch/patient",
"patient/*.rs",
"user/*.cruds"
]
}
3. Clinical Scopes (SMART v2)
SMART scopes control what applications are allowed to access:
# Scope format (v2):
# [context]/[resourceType].[cruds]
# Patient-level scopes (data của patient cụ thể)
patient/Patient.rs # Read Patient + Search
patient/Observation.rs # Read + Search Observations
patient/MedicationRequest.rs
# User-level scopes (theo quyền của user đang login)
user/Patient.cruds # Full CRUD + Search on Patient
user/Encounter.rs
user/*.rs # Read + Search tất cả resources
# System-level scopes (backend services)
system/Patient.rs
system/*.rs
CRUDS Operations
| Characters | Operation |
|---|---|
| c | Create |
| r | Read |
| u | Update |
| d | Delete |
| s | Search |
4. OAuth 2.0 Authorization Code Flow
# Step 1: Authorization Request
GET https://auth.hospital.vn/authorize
?response_type=code
&client_id=my-smart-app
&redirect_uri=https://smart-app.example.com/callback
&scope=launch/patient openid fhirUser patient/Patient.rs patient/Observation.rs
&state=random-state-value
&aud=https://fhir-server.hospital.vn/fhir/r5
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
# Step 2: Token Exchange
POST https://auth.hospital.vn/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=auth-code-from-callback
&redirect_uri=https://smart-app.example.com/callback
&client_id=my-smart-app
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "launch/patient openid fhirUser patient/Patient.rs patient/Observation.rs",
"id_token": "eyJ...",
"patient": "patient-001",
"encounter": "encounter-001",
"fhirUser": "Practitioner/practitioner-001"
}
# Step 3: FHIR API Calls
GET https://fhir-server.hospital.vn/fhir/r5/Patient/patient-001
Authorization: Bearer eyJ...
5. SMART Backend Services (System-to-System)
No user interaction required — use client_credentials with JWT assertions.
POST https://auth.hospital.vn/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=system/Patient.rs system/Observation.rs
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJ...signed_jwt...
6. CDS Hooks — Clinical Decision Support
CDS Hooks allow applications to provision clinical suggestion at the time of decision making in the EHR.
{
"hookInstance": "uuid-001",
"hook": "patient-view",
"fhirServer": "https://fhir-server.hospital.vn/fhir/r5",
"fhirAuthorization": {
"access_token": "eyJ...",
"token_type": "Bearer",
"scope": "patient/Patient.rs patient/Observation.rs"
},
"context": {
"userId": "Practitioner/practitioner-001",
"patientId": "patient-001"
}
}
CDS Response (Cards)
{
"cards": [
{
"uuid": "card-001",
"summary": "HbA1c cao — Cần điều chỉnh thuốc tiểu đường",
"detail": "HbA1c gần nhất: 8.5% (2025-01-10). Mục tiêu: < 7%. Xem xét tăng liều Metformin hoặc thêm thuốc mới.",
"indicator": "warning",
"source": {
"label": "Diabetes Management CDS",
"url": "https://cds.hospital.vn"
},
"suggestions": [
{
"label": "Kê đơn Metformin 1000mg",
"actions": [
{
"type": "create",
"description": "Tạo MedicationRequest Metformin 1000mg",
"resource": {
"resourceType": "MedicationRequest",
"status": "draft",
"intent": "proposal"
}
}
]
}
]
}
]
}
7. Summary
SMART on FHIR — OAuth 2.0 + FHIR for third-party health apps
EHR Launch — Open the app from within the EHR, get the available context
Standalone Launch — The app runs independently, asking for permissions on its own
Clinical Scopes — patient/*, user/*, system/* with cruds permissions
Backend Services — System-to-system, JWT client assertion
CDS Hooks — Decision support at point-of-care