Lingkup peluncuran mandiri SMART pada cakupan sumber daya FHIR untuk HealthLake

SMART pada cakupan FHIR OAuth 2.0 didukung oleh HealthLake

HealthLake menggunakan OAuth 2.0 sebagai protokol otorisasi. Menggunakan protokol ini di server otorisasi Anda memungkinkan Anda untuk menentukan izin penyimpanan HealthLake data (membuat, membaca, memperbarui, menghapus, dan mencari) untuk sumber daya FHIR yang dapat diakses oleh aplikasi klien.

SMART on FHIR framework mendefinisikan satu set cakupan yang dapat diminta dari server otorisasi. Misalnya, aplikasi klien yang hanya dirancang untuk memungkinkan pasien melihat hasil lab mereka atau melihat detail kontak mereka hanya boleh diizinkan untuk meminta read cakupan.

catatan

HealthLake menyediakan dukungan untuk SMART pada FHIR V1 dan V2 seperti yang dijelaskan di bawah ini. SMART di FHIR AuthorizationStrategydiatur ke salah satu dari tiga nilai berikut saat penyimpanan data Anda dibuat:

SMART_ON_FHIR_V1— Support hanya untuk SMART di FHIR V1, yang mencakup izin read (read/search) dan write (create/update/delete).
SMART_ON_FHIR— Support untuk SMART pada FHIR V1 dan V2, yang mencakupcreate,,read, updatedelete, dan search izin.
AWS_AUTH— Strategi AWS HealthLake otorisasi default; tidak berafiliasi dengan SMART di FHIR.

Lingkup peluncuran mandiri

HealthLake mendukung lingkup launch/patient mode peluncuran mandiri.

Dalam mode peluncuran mandiri, aplikasi klien meminta akses ke data klinis pasien karena pengguna dan pasien tidak diketahui oleh aplikasi klien. Dengan demikian, permintaan otorisasi aplikasi klien secara eksplisit meminta ruang lingkup pasien dikembalikan. Setelah otentikasi berhasil, server otorisasi mengeluarkan token akses yang berisi ruang lingkup pasien peluncuran yang diminta. Konteks pasien yang diperlukan disediakan bersama token akses dalam respons server otorisasi.

Cakupan mode peluncuran yang didukung
Lingkup	Deskripsi
`launch/patient`	Parameter dalam permintaan otorisasi OAuth 2.0 yang meminta agar data pasien dikembalikan dalam respons otorisasi.

SMART pada cakupan sumber daya FHIR untuk HealthLake

HealthLake mendefinisikan tiga tingkat SMART pada cakupan sumber daya FHIR.

patientcakupan memberikan akses ke data spesifik tentang satu Pasien.
usercakupan memberikan akses ke data tertentu yang dapat diakses pengguna.
systemcakupan memberikan akses ke semua sumber daya FHIR yang ditemukan di penyimpanan HealthLake data.

Bagian berikut mencantumkan sintaks untuk membangun cakupan sumber daya FHIR menggunakan SMART pada FHIR V1 atau SMART di FHIR V2.

catatan

Strategi otorisasi SMART on FHIR diatur saat penyimpanan data Anda dibuat. Untuk informasi selengkapnya, lihat AuthorizationStrategy di dalam Referensi API AWS HealthLake .

SMART pada cakupan FHIR V1 didukung oleh HealthLake

Saat menggunakan SMART pada FHIR V1, sintaks umum untuk membangun cakupan sumber daya FHIR untuk berikut. HealthLake Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol Salin.


('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')

SMART pada cakupan otorisasi yang didukung FHIR v1
Sintaks lingkup	Contoh ruang lingkup	Hasil
`patient/(fhir-resource \| '').('read' \| 'write' \| '')`	`patient/AllergyIntolerance.*`	Aplikasi klien pasien memiliki read/write akses tingkat instance ke semua alergi yang tercatat.
`user/(fhir-resource \| '').('read' \| 'write' \| '')`	`user/Observation.read`	Aplikasi klien pengguna memiliki read/write akses tingkat instance ke semua pengamatan yang direkam.
`system/('read' \| 'write' \| *)`	`system/.`	Aplikasi klien sistem memiliki read/write akses ke semua data sumber daya FHIR.

SMART pada cakupan FHIR V2 didukung oleh HealthLake

Saat menggunakan SMART di FHIR V2, sintaks umum untuk membangun cakupan sumber daya FHIR untuk berikut. HealthLake Untuk melihat seluruh jalur URL dalam contoh berikut, gulir ke atas tombol Salin.


('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')

catatan

Untuk menggunakan SMART pada FHIR V2, Anda harus meneruskan nilai permission-v2ke dalam capabilities string metadata, yang merupakan anggota dari tipe data. IdentityProviderConfiguration

HealthLake mendukung cakupan granular. Untuk informasi lebih lanjut, lihat cakupan granular yang didukung di Panduan Implementasi Inti AS FHIR.

SMART pada cakupan otorisasi yang didukung FHIR V2
Sintaks lingkup	Contoh lingkup V1	Hasil
`patient/Observation.rs`	`user/Observation.read`	Izin untuk membaca dan mencari `Observation` sumber daya untuk pasien saat ini.
`system/*.cruds`	`system/.`	Aplikasi klien sistem memiliki akses create/read update/delete penuh//pencarian ke semua data sumber daya FHIR.

SMART pada V2.2 cakupan FHIR didukung oleh HealthLake

V2.2 memperluas cakupan V2 dengan pemfilteran berbasis parameter pencarian. Server otorisasi sekarang dapat mengeluarkan cakupan yang membatasi akses dengan karakteristik data tertentu dan tidak hanya berdasarkan jenis sumber daya dan operasi CRUDS.

Semuanya dari V2 tetap tidak berubah. V2.2 murni aditif:

Cakupan V2 yang ada (tanpa filter) terus berfungsi seperti sebelumnya.
Tata bahasa V2 diperluas dengan string ?param=value kueri opsional.
Tidak ada perubahan pada tingkat lingkup (patient/user/system), jenis sumber daya, atau huruf CRUDS.

Prasyarat

Sebelum mengaktifkan SMART di FHIR V2.2, pastikan hal berikut:

Penyimpanan data Anda dibuat dengan AuthorizationStrategy set to SMART_ON_FHIR (mendukung V1 dan V2). Penyimpanan data menggunakan SMART_ON_FHIR_V1 atau AWS_AUTH tidak memenuhi syarat.
Penyimpanan data Anda sudah termasuk permission-v2 dalam capabilities array. V2.2 aditif karena memperpanjang V2 dan tidak dapat digunakan secara mandiri.
Lambda IDP Anda dikonfigurasi untuk memvalidasi dan melewati format cakupan (cakupan V2.2 yang berisi sintaks kueri?).

Mengaktifkan V2.2

Jalur pemberdayaan tergantung pada apakah Anda membuat penyimpanan data baru atau memperbarui yang sudah ada.

Menyimpan data baru

Saat membuat penyimpanan data baru, tambahkan permission-v2.2 ke capabilities array di Metadata bidang IdentityProviderConfiguration:


"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]

Penyimpanan data yang ada

Untuk mengaktifkan SMART di FHIR V2.2 pada penyimpanan data yang ada, tambahkan permission-v2.2 ke capabilities array di Metadata bidang Anda IdentityProviderConfigurationdan kirimkan perubahan denganUpdateFHIRDatastore. Untuk informasi selengkapnya, lihat Memperbarui penyimpanan HealthLake data.

Persyaratan:

permission-v2harus tetap dalam array. V2.2 memperluas V2 dan tidak dapat digunakan sendiri.
AuthorizationStrategyharus SMART_ON_FHIR (tidak SMART_ON_FHIR_V1 atauAWS_AUTH).
Memperbarui konfigurasi penyedia identitas menggantikannya secara penuh, jadi sertakan semua bidang dan kemampuan yang ada bersama denganpermission-v2.2.

Perubahan segera berlaku, tanpa downtime. Untuk memverifikasi, ambil Dokumen Penemuan (membutuhkan SigV4):


GET {healthlake-endpoint}/r4/.well-known/smart-configuration

Jika capabilities array dalam respons termasukpermission-v2.2, SMART di FHIR V2.2 aktif.

Sintaks lingkup yang diperluas

Tata bahasa V2 diperluas dengan string kueri opsional:


V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]

V2.2 komponen string kueri lingkup
Komponen	Deskripsi
`?param=value`	Search-parameter menyaring. Hanya sumber daya yang cocok dengan kriteria ini yang dapat diakses.
`&param=value`	Filter tambahan. Beberapa filter di-edD — semua harus cocok.

Aturan:

Filter hanya berlaku untuk jenis sumber daya yang ditentukan dalam ruang lingkup. Wildcard (*) dengan filter tidak didukung.
Parameter harus valid untuk jenis sumber daya per konfigurasi pencarian penyimpanan data Anda (periksa viaGET /r4/metadata).
String lingkup penuh (misalnya,patient/Observation.rs?category=laboratory) adalah nilai literal yang muncul dalam parameter lingkup OAuth 2.0 dan klaim token scp akses.
URL-encode karakter khusus per RFC 6749 dalam permintaan otorisasi (misalnya, | →). %7C
Untuk parameter tanggal, angka, dan kuantitas, V2.2 mendukung pembanding awalan (misalnya,?date=eq2023-01-01). V2.2 juga mendukung pengubah parameter pencarian.

Contoh lingkup

V2.2 contoh lingkup
Lingkup	Akses diberikan
`patient/DiagnosticReport.rs?category=LAB`	Hanya `DiagnosticReport` sumber daya di `category` mana`LAB`.
`patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R`	Hanya `Observation` sumber daya dengan label keamanan`Restricted`.
`patient/Observation.rs?date=ge2023-01-01`	Hanya `Observation` sumber daya tertanggal pada atau setelah 1 Januari 2023.
`patient/Observation.rs?category=laboratory&status=final`	Hanya `Observation` sumber daya yang lab DAN final.
`user/Condition.rs?clinical-status=active`	Hanya `Condition` sumber daya aktif.

Perilaku penegakan

Saat token menyertakan V2.2 cakupan, HealthLake terapkan filter per operasi:

V2.2 penegakan per operasi
Operasi	Perilaku
Baca (`r`)	Berhasil hanya jika sumber daya cocok dengan semua filter lingkup. Jika tidak mengembalikan 403.
Cari (`s`)	Filter lingkup berpotongan dengan kueri. Hanya sumber daya yang cocok yang dikembalikan.
Create/Update (`c`/`u`)	Sumber daya harus memenuhi filter lingkup untuk ditulis. Jika tidak mengembalikan 403.
Hapus (`d`)	Sumber daya target harus cocok dengan filter lingkup. Jika tidak mengembalikan 403.

Ruang lingkup diutamakan

Beberapa V2.2 cakupan untuk jenis sumber daya yang sama disatukan (ATAU lintas cakupan).
Cakupan V2 yang lebih luas tanpa filter (misalnya,patient/Observation.rs) memberikan akses penuh terlepas dari V2.2 cakupan yang lebih sempit dalam token yang sama.
V2.2 cakupan pada penyimpanan data tanpa permission-v2.2 diaktifkan diabaikan secara diam-diam.

Batasan

Berikut ini tidak didukung dalam filter V2.2 lingkup:

Parameter pencarian komposit (misalnya,code-value-quantity).
Parameter pencarian berantai (misalnya,subject:Patient.name=Smith).
_include/parameter _revinclude pencarian.
$export/$davinci-data-export(Data Massal) — V2.2 filter tidak berlaku; ekspor massal menggunakan cakupan V2.
Jenis sumber daya wildcard dikombinasikan dengan filter (misalnya, patient/*.rs?category=LAB tidak valid). Anda harus menentukan jenis sumber daya eksplisit saat menggunakan filter parameter pencarian (misalnya,). patient/Observation.rs?category=LAB

Pemecahan masalah
Gejala	Penyebab	Perbaiki
Cakupan token tidak dikenali	V2.2 tidak diaktifkan di penyimpanan data	Periksa `/.well-known/smart-configuration` dan minta pemberdayaan melalui tiket dukungan.
403 pada sumber daya yang ada	Sumber daya tidak cocok dengan filter lingkup	Verifikasi nilai sumber daya terhadap parameter lingkup.
Hasil pencarian kosong	Filter lingkup lebih sempit dari kueri	Hasil adalah persimpangan filter kueri dan ruang lingkup.
`InvalidScope` kesalahan	Parameter pencarian tidak valid dalam lingkup	Konfirmasikan parameter melalui `/metadata` CapabilityStatement.

End-to-end contoh

Skenario: Aplikasi pasien seharusnya hanya menampilkan hasil lab yang diselesaikan mulai tahun 2023 dan seterusnya.

Server otorisasi mengeluarkan token dengan cakupan:


patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01

Panggilan klien HealthLake:


GET {endpoint}/r4/Observation?patient=Patient/123

HealthLake memberlakukan filter lingkup. Respons hanya berisi Observation sumber daya di mana category=laboratory status=final DAN DAN date ≥ 2023-01-01 - meskipun klien meminta semua Pengamatan.

Konvensi Dokumen

Autentikasi

Validasi token