Terhubung 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 apa pun yang telah mengadopsi standar tersebut.

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

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

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

Kerangka 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 Framework Peluncuran Aplikasi SMART.

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

Cakupan

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

  • patient
  • user
  • system
Konteks peluncuran

Menjelaskan pasien, pertemuan, atau konteks lain saat ini 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 penerapan akses SMART di 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 dan konteks pasien yang diberikan, Cloud Healthcare API tidak menentukan alur kerja peluncuran yang perlu digunakan aplikasi klien dengan server otorisasi eksternal.

Menetapkan dan memvalidasi cakupan otorisasi SMART

Jika menggunakan SMARTProxy, Anda dapat melewati bagian ini. SMARTProxy menetapkan 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, lalu 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 header HTTP SMART di FHIR berikut saat membuat permintaan dari proxy. Aplikasi klien tidak perlu menetapkan 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 pasien permintaan. Saat Anda menetapkan header ini, jenis resource apa pun dalam permintaan yang memenuhi syarat untuk berada di kompartemen pasien harus termasuk dalam kompartemen pasien dari ID pasien yang diberikan. Cloud Healthcare API menerapkan kontrol akses ini.
  • X-Authorization-Subject: ID untuk pengguna akhir yang mengakses aplikasi klien SMART di FHIR. Cloud Healthcare API mencatat subjek 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 mengeluarkan 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 untuk cara server otorisasi membuat token JWT SMART. Misalnya, aplikasi Anda mungkin terdaftar untuk sebagian cakupan, atau aplikasi mungkin menampilkan widget pemilihan pasien untuk menetapkan konteks pasien.

Jika tidak memiliki server otorisasi yang mengonfigurasi token JWT SMART, 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 didekode, token akses 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 di FHIR di Cloud Healthcare API

Bagian ini menjelaskan langkah-langkah yang perlu Anda lakukan untuk mulai menggunakan SMART di 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, lalu meneruskannya ke Cloud Healthcare API menggunakan empat header HTTP.
  4. Cloud Healthcare API menerima header dan memvalidasinya untuk menerapkan kontrol akses pada permintaan. Cloud Healthcare API kemudian menampilkan respons melalui SMARTProxy ke klien.

Mengonfigurasi akun layanan Google Cloud

Proxy hanya dapat memiliki satu Google Cloud akun layanan. 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 akun utama Log Audit Cloud 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 menggunakan akun layanannya sendiri, dan alamat email akun layanan adalah alamat email utama, sehingga pemanggil asli akan disamarkan. Untuk menyimpan pengguna akhir ke metadata log audit, teruskan alamat email pengguna akhir di kolom sub token JWT.

Mengonfigurasi penyimpanan FHIR

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

Membuat permintaan SMART di FHIR

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

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

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 di FHIR ke penyimpanan FHIR, kontrol akses terjadi dalam urutan berikut:

  1. Cloud Healthcare API memeriksa izin di 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 permintaan.

Kompartemen pasien sangat penting untuk logika penerapan akses di Cloud Healthcare API. SMART on FHIR memiliki daftar jenis resource FHIR yang memenuhi syarat untuk disertakan dalam kompartemen pasien. Jenis resource juga memiliki kriteria penyertaan sendiri. Di bagian lain dalam bagian ini, 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 untuk kompartemen pasien".

Permintaan SMART di FHIR ke FHIR store 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.

  • Jika Anda menyediakan cakupan patient yang berisi jenis resource yang tidak memenuhi syarat untuk 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 ada dengan cakupan user, jenis resource yang memenuhi syarat kompartemen pasien dibatasi untuk konteks pasien. Jenis resource lainnya mengabaikan konteks pasien.

  • Kehadiran konteks pasien membatasi jenis resource yang memenuhi syarat kompartemen pasien untuk pasien tertentu. Misalnya, resource Pengamatan harus memiliki referensi kolom subject resource Pasien yang diberikan agar Pengamatan dapat diakses. Lihat jenis akses kompartemen pasien di Resource CompartmentDefinition - Content untuk mengetahui daftar kolom di setiap jenis resource kompartemen pasien yang harus dirujuk ke Pasien tertentu agar resource 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 berlaku untuk setiap resource.