Lesson 0017 · FHIR · Modul SMART · ±24 menit

SMART = OAuth 2.0 untuk FHIR; EHR launch vs standalone, discovery

OAuth2 yang sudah Anda kenal, ditambah tiga hal khas kesehatan: launch dari EHR, scopes per resource FHIR, dan konteks pasien

Target lesson ini: Anda bisa menjelaskan apa yang ditambahkan SMART di atas OAuth 2.0, membedakan EHR launch (iss + launch) dari standalone launch (launch/patient), dan menyebut apa yang didapat app dari discovery .well-known/smart-configuration.

Modul ini dimulai dari peta besarnya. Di modul Bulk Data (lesson 0013–0016) service Node menarik data massal; di sini pertanyaannya: bagaimana sebuah app, termasuk React SPA, mendapat izin mengakses data pasien.

Versi yang dipakai: SMART App Launch IG v2.2.0 (STU 2.2), versi terbit saat ini, berbasis FHIR R4 (4.0.1). ^[1] Dasar OAuth2/JWT, 401 vs 403, CORS, dan localStorage vs cookie HttpOnly tidak diulang di sini; kalau perlu penyegaran, lihat lesson 0017 (track .NET). Fokus lesson ini hanya yang khas SMART.

1. Peta besar: SMART = OAuth 2.0 yang diprofilkan untuk FHIR

SMART App Launch menghubungkan app pihak ketiga ke data EHR, dan app bisa diluncurkan dari dalam maupun dari luar UI EHR. Secara teknis ini adalah "profile on OAuth 2.0" untuk app yang butuh identitas user atau resource FHIR. ^[2] Padanan dunia JS: "Login with Google" di SPA dengan authorization code + PKCE, plus tiga tambahan:

Yang Anda kenal (OAuth2 di SPA)	Tambahan SMART
App selalu dimulai dari tombol "Login"	App juga bisa diluncurkan oleh EHR dari dalam rekam medis yang sedang dibuka (EHR launch)
Endpoint OAuth di-hardcode per provider	Endpoint ditemukan lewat `[fhir-base]/.well-known/smart-configuration`
Scope bebas (`read:user`, `repo`)	Scope mengikuti resource type FHIR: `patient/Observation.rs`
Token response: token saja	Token response juga membawa launch context: `"patient": "123"`

Yang tidak diatur SMART: izin dasar user di EHR. SMART hanya mendelegasikan sebagian izin yang sudah dimiliki user ke app, "on top of an EHR's existing user and permissions management system". ^[2] Mekanisme seperti session time-out dan security auditing yang diwajibkan HIPAA juga di luar cakupan profile ini. ^[2]

2. Dua cara mulai: EHR launch vs standalone launch, lalu discovery

Langkah tingkat atas SMART App Launch: ^[2]

Register app (sekali)→ Launch: EHR / standalone→ .well-known/smart-configuration→ authorization code→ access token→ FHIR API→ refresh

	EHR launch	Standalone launch
Siapa memulai	User sudah di sesi EHR lalu membuka app (mis. dari tab rekam medis)	User membuka app dari luar EHR (mis. ikon di home screen)
Yang diterima app di awal	Launch URL dibuka dengan `iss` (FHIR endpoint EHR) dan `launch` (handle opaque)	Tidak ada; app sudah tahu server FHIR mana yang dituju
Cara minta konteks	Scope `launch` + parameter `launch=xyz123` dikirim balik saat authorize	Scope `launch/patient`: EHR bisa menampilkan pemilih pasien

Kutipan tabel: ^[2] ^[3]

Location: https://app/launch?iss=https%3A%2F%2Fehr%2Ffhir&launch=xyz123

Setelah tahu base URL FHIR (dari iss atau konfigurasi), app melakukan discovery: GET ke base URL + /.well-known/smart-configuration. Server SHALL menjawab JSON; capabilities, token_endpoint, dan code_challenge_methods_supported wajib ada, authorization_endpoint wajib bila server mendukung launch. Dulu sebagian info ini ada di CapabilityStatement; mekanisme itu sekarang deprecated. ^[4]

// GET https://ehr.example.com/fhir/.well-known/smart-configuration  (ilustrasi, dipersingkat)
{
  "authorization_endpoint": "https://ehr.example.com/auth/authorize",
  "token_endpoint": "https://ehr.example.com/auth/token",
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "offline_access"],
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "context-ehr-patient",
                   "context-standalone-patient", "permission-patient", "permission-v2", "sso-openid-connect"]
}

capabilities memberi tahu app fitur apa yang didukung: mode launch (launch-ehr, launch-standalone), tipe client (client-public, client-confidential-symmetric, client-confidential-asymmetric), konteks, dan sintaks scope (permission-v1, permission-v2). ^[4] Untuk browser app, server SHALL mengaktifkan CORS: discovery untuk origin apa pun, token endpoint dan FHIR API hanya untuk origin yang terdaftar. ^[2]

Latihan 1 — EHR launch dan discovery

Jawab tanpa scroll ke atas. Soal yang sama akan muncul lagi, diacak, di review 0027.

Kuis di lesson ini adalah feedback cepat, bukan bukti penguasaan; yang dicatat hanya hasil review 0027.

Latihan lisan — Jawab lisan

Pasang timer, jawab dengan suara keras seolah sedang interview, baru buka jawaban contoh. Soal ini juga ada di bank soal dan bisa ditarik review 0027.

Soal ini merangkum seluruh modul SMART. Bagian PKCE, scopes, dan fhirclient dibahas di lesson 0018–0020; kalau belum bisa menjawabnya sekarang, ulangi soal ini setelah lesson 0020.

"Bagaimana React app Anda mendapat akses ke data pasien di EHR? Apa itu SMART on FHIR?" (90 detik)

Bandingkan dengan jawaban contoh dan checklist-nya

"SMART App Launch adalah profile OAuth 2.0, plus OpenID Connect, di atas FHIR. Ada dua cara mulai: EHR launch, EHR membuka launch URL kami dengan iss dan launch; atau standalone, user membuka app langsung dan kami meminta launch/patient. App mengambil [iss]/.well-known/smart-configuration untuk tahu authorize dan token endpoint, lalu redirect ke authorize dengan response_type=code, scopes seperti launch patient/Observation.rs openid fhirUser, state, aud, dan PKCE S256. Karena React SPA adalah public client, tidak ada client secret; PKCE yang melindungi code. Setelah redirect balik, app memvalidasi state, menukar code + code_verifier, dan menerima access token, scope yang benar-benar diberikan, serta patient ID sebagai launch context. Setiap request FHIR membawa Authorization: Bearer. Di React saya pakai fhirclient: authorize() di launch page, ready() di redirect page."

Checklist: apakah Anda menyebut…

SMART = profile OAuth 2.0 (+ OIDC) untuk app FHIR?
EHR launch (iss + launch) vs standalone (launch/patient)?
discovery lewat .well-known/smart-configuration?
authorization code + PKCE S256, tanpa client secret di SPA?
state divalidasi dan aud = FHIR base URL?
token response: access token, scope yang diberikan, patient context; lalu Bearer?

Lulus kalau minimal 4 dari 6.

Berikutnya, lesson 0018: setelah discovery app tahu URL authorize dan token. Bagaimana React SPA menukar authorization code menjadi token tanpa client secret?

Istilah: GLOSSARY.md (bagian "Keamanan dan SMART on FHIR") · Sumber: RESOURCES.md

Sumber: [1] SMART App Launch IG v2.2.0 (STU 2.2) · [2] App Launch: Launch and Authorization · [3] Scopes and Launch Context · [4] Conformance (.well-known/smart-configuration)