Menghubungkan ke aplikasi menggunakan SMART di FHIR

Halaman ini menjelaskan cara menggunakan standar SMART (Substitutable Medical Applications, Reusable Technologies) di FHIR v1.1.0 untuk mengakses data di penyimpanan FHIR di Cloud Healthcare API.

Ringkasan

SMART di FHIR adalah standar data yang memungkinkan aplikasi mengakses informasi dalam sistem catatan kesehatan elektronik (EHR). Developer aplikasi dapat menulis satu aplikasi yang terhubung ke sistem EHR mana pun yang telah menggunakan standar tersebut.

Misalnya, jika Anda memiliki data pasien yang disimpan di penyimpanan FHIR di Cloud Healthcare API, Anda dapat mengembangkan aplikasi yang melakukan hal berikut:

  1. Mengautentikasi ke penyimpanan FHIR.
  2. Mengambil data pasien.
  3. Menampilkan data pasien di antarmuka pengguna.

SMART di FHIR mendukung model otorisasi OpenID dan OAuth 2.0 untuk otorisasi dan autentikasi.

Framework Peluncuran Aplikasi SMART, cakupan, dan konteks peluncuran

Cloud Healthcare API mendukung Framework Peluncuran Aplikasi SMART, cakupan, dan konteks peluncuran sebagai berikut:

Framework Peluncuran Aplikasi SMART

Cloud Healthcare API mendukung Urutan peluncuran mandiri dari SMART App Launch Framework.

Aplikasi dapat diluncurkan dari dalam sesi sistem EHR atau Portal Pasien yang sudah ada, yang keduanya disebut "peluncuran EHR", atau sebagai aplikasi mandiri.

Cakupan

Cakupan data klinis menentukan izin baca dan tulis untuk akses khusus pasien dan tingkat pengguna. Cloud Healthcare API mendukung cakupan data berikut yang ditentukan pada Cakupan untuk meminta data klinis:

  • patient
  • user
  • system
Meluncurkan konteks

Menjelaskan pasien saat ini, pertemuan, atau konteks lain tempat permintaan dibuat. Cloud Healthcare API mendukung konteks peluncuran Pasien dari Cakupan untuk meminta data konteks.

Mengonfigurasi server otorisasi untuk SMART di FHIR

Cloud Healthcare API menyediakan dukungan bawaan untuk SMART pada penerapan akses FHIR berdasarkan cakupan otorisasi SMART input dan konteks pasien. Administrator penyimpanan FHIR membuat dan mengonfigurasi server otorisasi di luar Cloud Healthcare API yang memberikan cakupan otorisasi SMART dan konteks pasien.

Jika aplikasi klien mendapatkan token akses yang mewakili cakupan otorisasi SMART yang diberikan dan konteks pasien, Cloud Healthcare API tidak menentukan alur kerja peluncuran mana yang perlu digunakan aplikasi klien dengan server otorisasi eksternal.

Menetapkan dan memvalidasi cakupan otorisasi SMART

Jika menggunakan SMARTProxy, Anda dapat melewati bagian ini. SMARTProxy menyetel dan memvalidasi cakupan otorisasi SMART secara otomatis.

Cakupan otorisasi SMART menggunakan format berikut:

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

Cakupan otorisasi SMART dan konteks pasien diteruskan ke Cloud Healthcare API menggunakan header HTTP X-Authorization-. Cloud Healthcare API menggunakan header ini untuk menerapkan kontrol akses pada data di penyimpanan FHIR.

Server otorisasi Anda memberikan cakupan otorisasi SMART dan konteks pasien, serta mengenkodenya dalam token akses. Proxy kemudian membaca informasi dalam token akses dan meneruskannya ke header permintaan FHIR.

Jika tidak memiliki server otorisasi, Anda dapat menggunakan akselerator interoperabilitas berbasis Apigee HealthAPIx di Apigee.

Gunakan SMART berikut pada header HTTP FHIR saat membuat permintaan dari proxy. Aplikasi klien tidak perlu menyetel header ini karena hanya diteruskan dari proxy ke Cloud Healthcare API.

  • X-Authorization-Scope: Satu atau beberapa cakupan otorisasi yang menggunakan format cakupan otorisasi SMART standar. Misalnya, menetapkan cakupan otorisasi ke user/Observation.read berarti permintaan hanya dapat membaca resource Observation. Cloud Healthcare API menerapkan kontrol akses ini.
  • X-Authorization-Patient: Konteks permintaan pasien. Saat Anda menetapkan header ini, semua jenis resource dalam permintaan yang memenuhi syarat untuk berada di kompartemen pasien harus berada dalam kompartemen pasien dari ID pasien yang diberikan. Cloud Healthcare API menerapkan kontrol akses ini.
  • X-Authorization-Subject: ID untuk pengguna akhir yang mengakses SMART di aplikasi klien FHIR. Cloud Healthcare API mencatat subjek ke dalam Log audit.
  • X-Authorization-Issuer: Penerbit token akses SMART. Cloud Healthcare API mencatat penerbit ke dalam Log audit.

Mengonfigurasi token akses server otorisasi

Untuk memunculkan token JWT, Anda harus mengonfigurasi server otorisasi. Token JWT berisi cakupan otorisasi SMART dan, secara opsional, konteks pasien. Cloud Healthcare API tidak memiliki persyaratan khusus tentang cara server otorisasi membuat token SMART JWT. Misalnya, aplikasi Anda mungkin terdaftar untuk sebagian cakupan, atau aplikasi mungkin menampilkan widget pemilihan pasien untuk menyetel konteks pasien.

Jika tidak memiliki server otorisasi yang mengonfigurasi token SMART JWT, Anda dapat menggunakan akselerator interoperabilitas berbasis Apigee HealthAPIx di Apigee untuk menyiapkan server autentikasi yang menandatangani token JWT.

Contoh token akses

Contoh berikut menunjukkan token akses yang dienkode dalam base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Setelah mendekode token akses, token tersebut akan berisi payload berikut:

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

Mengonfigurasi SMART pada FHIR di Cloud Healthcare API

Bagian ini menjelaskan langkah-langkah yang perlu Anda lakukan untuk mulai menggunakan SMART pada FHIR dengan data di Cloud Healthcare API.

Mengonfigurasi SMARTProxy

Jika Anda menggunakan server otorisasi Anda sendiri, bukan SMARTProxy, lewati bagian ini dan lanjutkan ke Mengonfigurasi akun layanan Google Cloud.

SMARTProxy adalah proxy open source dari Google yang menyediakan fitur berikut:

  • Mengizinkan Cloud Healthcare API menerima dan memvalidasi token akses SMART.
  • Memungkinkan implementasi FHIR di Cloud Healthcare API untuk menyertakan token akses SMART sebagai bagian dari model izin dan pengelolaan API.

Saat Anda membuat permintaan untuk mengambil data dari Cloud Healthcare API melalui SMARTProxy, permintaan tersebut akan mengikuti langkah-langkah berikut:

  1. SMARTProxy menerima permintaan yang berisi token SMART dari klien.
  2. SMARTProxy memvalidasi token SMART melalui server otorisasi JWT Anda.
  3. SMARTProxy membaca cakupan dan konteks pasien dari token SMART dan meneruskannya ke Cloud Healthcare API menggunakan empat header HTTP.
  4. Cloud Healthcare API menerima header dan memvalidasinya untuk menerapkan kontrol akses pada permintaan. Kemudian, Cloud Healthcare API menampilkan respons melalui SMARTProxy ke klien.

Mengonfigurasi akun layanan Google Cloud

Proxy hanya dapat memiliki satu akun layanan Google Cloud. Jika beberapa klien menggunakan proxy yang sama, klien tersebut harus menggunakan akun layanan yang sama. Berhati-hatilah saat berbagi akun layanan dengan beberapa klien karena alasan berikut:

  • Untuk membaca data FHIR di Cloud Healthcare API, akun layanan memiliki izin baca dan tulis yang luas.

  • Alamat email utama Cloud Audit Logs terikat dengan akun layanan.

    Misalnya, jika Anda memanggil Cloud Healthcare API menggunakan Akun Google Anda untuk autentikasi, Cloud Audit Logs akan mencatat alamat email Anda sebagai alamat email utama. Saat Anda menggunakan proxy untuk memanggil Cloud Healthcare API, proxy tersebut akan menggunakan akun layanannya sendiri, dan alamat email akun layanan adalah alamat email utama, sehingga penelepon asli akan disamarkan. Untuk menyimpan pengguna akhir ke metadata log audit, teruskan alamat email pengguna akhir di kolom sub pada token JWT.

Mengonfigurasi penyimpanan FHIR

Anda tidak perlu mengonfigurasi penyimpanan FHIR yang menyimpan data FHIR yang Anda akses.

Membuat SMART pada permintaan FHIR

Bagian ini memberikan ringkasan tentang SMART yang didukung pada metode FHIR di Cloud Healthcare API dan cara penerapan akses resource saat Anda membuat SMART pada permintaan FHIR.

Saat membuat permintaan, server otorisasi Anda bertanggung jawab untuk membuat token akses dengan cakupan otorisasi SMART yang relevan dan konteks peluncuran.

Metode yang didukung

Cloud Healthcare API mendukung SMART di FHIR untuk semua metode projects.locations.datasets.fhirStores.fhir kecuali untuk hal berikut:

Penerapan akses resource

Saat membuat permintaan SMART pada FHIR ke penyimpanan FHIR, kontrol akses terjadi dalam urutan berikut:

  1. Cloud Healthcare API memeriksa izin pada akun layanan Google Cloud yang dikonfigurasi di proxy. Jika akun layanan memiliki izin IAM yang benar di penyimpanan FHIR, permintaan akan dilanjutkan.
  2. Cloud Healthcare API memverifikasi apakah token SMART memiliki izin yang sesuai untuk mengakses setiap resource FHIR yang diminta.

Kompartemen pasien sangat penting untuk logika penerapan akses di Cloud Healthcare API. SMART di FHIR memiliki daftar jenis resource FHIR yang memenuhi syarat untuk disertakan dalam kompartemen pasien. Jenis resource juga memiliki kriteria penyertaannya sendiri. Di bagian selanjutnya, jenis resource yang memenuhi syarat disebut "jenis resource yang memenuhi syarat kompartemen pasien". Jenis resource yang tidak memenuhi syarat disebut "jenis resource yang tidak memenuhi syarat di kompartemen pasien".

SMART pada permintaan FHIR ke toko FHIR harus memenuhi persyaratan berikut:

  • Berikan peran patient, user, atau system dalam cakupan otorisasi SMART. Jika memberikan peran patient, Anda harus memberikan konteks pasien. Konteks pasien adalah ID logis resource Pasien. Resource Pasien harus sudah ada di penyimpanan FHIR atau ada setelah permintaan dibuat. Jika tidak, Cloud Healthcare API akan menolak permintaan tersebut.

  • Saat membuat, membaca, memperbarui, atau menghapus resource, resourceType dan jenis operasi (read atau write) harus cocok. Jika tidak, Cloud Healthcare API akan menolak permintaan tersebut.

  • Jika Anda menyediakan cakupan patient yang berisi jenis resource yang tidak memenuhi syarat kompartemen pasien, seperti patient/Practitioner.*, pemeriksaan validasi cakupan akan gagal dan Cloud Healthcare API akan menolak cakupan tersebut.

  • Anda dapat menetapkan semua jenis resource dengan cakupan user. Jika konteks pasien ditampilkan dengan cakupan user, jenis resource yang memenuhi syarat kompartemen pasien dibatasi sesuai konteks pasien. Jenis sumber daya yang tersisa mengabaikan konteks pasien.

  • Kehadiran konteks pasien membatasi jenis resource yang memenuhi syarat bagi kompartemen pasien untuk pasien tertentu. Misalnya, resource Pengamatan harus memiliki referensi kolom subject ke resource Pasien yang diberikan agar Observation dapat diakses. Lihat jenis akses kompartemen pasien di Resource CompartmentDefinition - Content untuk mengetahui daftar kolom pada setiap jenis resource kompartemen pasien yang harus dirujuk ke Pasien yang ditentukan agar referensi dapat dipertimbangkan di dalam kompartemen pasien.

  • Permintaan dapat berisi cakupan patient dan user.

  • Jangan gunakan cakupan system dengan konteks pasien. Jika tidak, permintaan akan gagal.

  • Jangan gunakan cakupan system dengan cakupan patient atau cakupan user.

  • Jika Anda memanggil metode yang mengakses beberapa resource (misalnya, metode fhir.Patient-everything, fhir.executeBundle, atau fhir.search), kontrol akses akan diterapkan ke setiap resource.