חיבור לאפליקציות באמצעות SMART on FHIR

בדף הזה מוסבר איך להשתמש בתקן SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR v1.1.0 כדי לגשת לנתונים במאגרי FHIR ב-Cloud Healthcare API.

סקירה כללית

‫SMART on FHIR הוא תקן נתונים שמאפשר לאפליקציות לגשת למידע במערכות של סיכומי מצב בריאותי אלקטרוניים (EHR). מפתח אפליקציות יכול לכתוב אפליקציה אחת שמתחברת לכל מערכת EHR שאימצה את התקן.

לדוגמה, אם יש לכם נתוני מטופלים שמאוחסנים במאגר FHIR ב-Cloud Healthcare API, אתם יכולים לפתח אפליקציה שמבצעת את הפעולות הבאות:

  1. מתבצע אימות למאגר FHIR.
  2. אחזור הנתונים של המטופל.
  3. הצגת נתוני המטופל בממשק משתמש.

‫SMART on FHIR תומך במודלים של הרשאה OpenID ו-OAuth 2.0 לצורך הרשאה ואימות.

מסגרת ההפעלה של אפליקציות SMART, היקפים והקשר הפעלה

‫Cloud Healthcare API תומך ב-SMART App Launch Framework, בהיקפי גישה ובהקשר ההפעלה באופן הבא:

מסגרת להפעלת אפליקציות SMART

‫Cloud Healthcare API תומך ברצף ההפעלה העצמאי מתוך SMART App Launch Framework.

אפשר להפעיל אפליקציה מתוך מערכת EHR קיימת או מתוך פורטל מטופלים, שניהם נקראים 'הפעלה של EHR', או כאפליקציה עצמאית.

היקפים

היקפי הנתונים הקליניים מגדירים הרשאות קריאה וכתיבה לגישה ברמת המשתמש ולגישה ספציפית למטופל. ‫Cloud Healthcare API תומך בהיקפי הנתונים הבאים שמוגדרים בהיקפים לבקשת נתונים קליניים:

  • patient
  • user
  • system
הקשר ההפעלה

תיאור של המטופל הנוכחי, המפגש או הקשר אחר שבו מתבצעת הבקשה. ‫Cloud Healthcare API תומך בהקשר של הפעלת מטופל מתוך היקפי הרשאות לבקשת נתוני הקשר.

הגדרת שרת ההרשאות ל-SMART on FHIR

‫Cloud Healthcare API מספק תמיכה מובנית באכיפת גישה ל-SMART on FHIR על סמך היקפי ההרשאה של SMART והקשר המטופל. אדמינים של מאגר FHIR יוצרים ומגדירים שרת הרשאות מחוץ ל-Cloud Healthcare API, שמעניק היקפי הרשאות של SMART והקשר של המטופל.

אם אפליקציית לקוח מקבלת אסימון גישה שמייצג את היקפי ההרשאה שניתנו ב-SMART ואת ההקשר של המטופל, Cloud Healthcare API לא מציין באיזה תהליך עבודה של הפעלה אפליקציית הלקוח צריכה להשתמש עם שרת ההרשאה החיצוני.

הגדרה ואימות של היקפי הרשאות SMART

אם אתם משתמשים ב-SMARTProxy, אתם יכולים לדלג על הקטע הזה. ‫SMARTProxy מגדיר ומאמת באופן אוטומטי את היקפי ההרשאה של SMART.

הפורמט של היקפי הרשאה של SMART הוא:

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

היקפי הרשאה של SMART והקשרים של המטופלים מועברים אל Cloud Healthcare API באמצעות כותרות HTTP‏ X-Authorization-. ‫Cloud Healthcare API משתמש בכותרות האלה כדי לאכוף בקרת גישה לנתונים במאגרי FHIR.

שרת ההרשאות מעניק את היקפי ההרשאות של SMART ואת הקשר של המטופל ומקודד אותם בטוקן גישה. לאחר מכן, ה-proxy קורא את המידע בטוקן הגישה ומעביר אותו לכותרות של בקשת FHIR.

אם אין לכם שרת הרשאות, אתם יכולים להשתמש במאיץ האינטראופרביליות מבוסס Apigee‏ HealthAPIx ב-Apigee.

כששולחים בקשות מה-proxy, צריך להשתמש בכותרות ה-HTTP הבאות של SMART on FHIR. אפליקציית הלקוח לא צריכה להגדיר את הכותרות האלה כי הן מועברות רק מהשרת הפרוקסי אל Cloud Healthcare API.

  • ‫X-Authorization-Scope: היקף הרשאות אחד או יותר שמשתמשים בפורמטים סטנדרטיים של היקפי הרשאות SMART. לדוגמה, אם מגדירים את היקף ההרשאות ל-user/Observation.read, אפשר לבצע קריאה רק של משאב מסוג Observation. בקרת הגישה הזו נאכפת על ידי Cloud Healthcare API.
  • ‫X-Authorization-Patient: ההקשר של המטופל בבקשה. כשמגדירים את הכותרת הזו, כל סוגי המשאבים בבקשה שעומדים בדרישות להיות בתא של מטופל צריכים להיות שייכים לתא של המטופל של מזהה המטופל שצוין. ב-Cloud Healthcare API נאכפת בקרת הגישה הזו.
  • ‫X-Authorization-Subject: מזהה של משתמש הקצה שניגש לאפליקציית הלקוח SMART on FHIR. המערכת של Cloud Healthcare API מתעדת את הנושא ביומני ביקורת.
  • ‫X-Authorization-Issuer: הגורם שהנפיק את אסימון הגישה של SMART. ‫Cloud Healthcare API מתעד את המנפיק ביומני ביקורת.

הגדרת אסימוני הגישה של שרת ההרשאות

כדי להנפיק אסימון JWT, צריך להגדיר שרת הרשאות. אסימון ה-JWT כולל את היקפי ההרשאות של SMART, ואופציונלית את ההקשר של המטופל. ל-Cloud Healthcare API אין דרישות ספציפיות לגבי האופן שבו שרת ההרשאות יוצר את אסימון ה-JWT של SMART. לדוגמה, יכול להיות שהאפליקציה שלכם רשומה לקבוצת משנה של היקפי הרשאות, או שהאפליקציה מציגה ווידג'ט לבחירת מטופל כדי להגדיר את ההקשר של המטופל.

אם אין לכם שרת הרשאות שמגדיר אסימוני JWT של SMART, אתם יכולים להשתמש במאיץ האינטראופרביליות מבוסס-Apigee‏ HealthAPIx ב-Apigee כדי להגדיר שרת אימות שחותם על אסימוני JWT.

דוגמה לטוקן גישה

בדוגמה הבאה מוצג אסימון גישה שמקודד ב-base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

אחרי שמפענחים את אסימון הגישה, הוא מכיל את מטען הייעודי (payload) הבא:

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

הגדרת SMART on FHIR ב-Cloud Healthcare API

בקטע הזה מוסבר איך מתחילים להשתמש ב-SMART on FHIR עם נתונים ב-Cloud Healthcare API.

הגדרת SMARTProxy

אם אתם משתמשים בשרת הרשאות משלכם במקום ב-SMARTProxy, דלגו על הקטע הזה ועברו אל הגדרת חשבון שירות. Google Cloud

‫SMARTProxy הוא פרוקסי בקוד פתוח מבית Google, שמספק את התכונות הבאות:

  • מאפשרת ל-Cloud Healthcare API לקבל ולאמת אסימוני גישה של SMART.
  • מאפשרת להטמעת FHIR ב-Cloud Healthcare API לכלול טוקנים של SMART Access כחלק מניהול ה-API וממודל ההרשאות.

כששולחים בקשה לאחזור נתונים מ-Cloud Healthcare API דרך SMARTProxy, הבקשה עוברת את השלבים הבאים:

  1. ‫SMARTProxy מקבל בקשה שמכילה אסימון SMART מלקוח.
  2. ‫SMARTProxy מאמת את אסימון SMART דרך שרת ההרשאות של JWT.
  3. ‫SMARTProxy קורא את ההיקפים ואת ההקשר של המטופל מטוקן SMART ומעביר אותם אל Cloud Healthcare API באמצעות ארבע כותרות HTTP.
  4. ה-Cloud Healthcare API מקבל את הכותרות ומאמת אותן כדי לאכוף בקרת גישה בבקשה. לאחר מכן, Cloud Healthcare API מחזיר תגובה ללקוח דרך SMARTProxy.

הגדרת Google Cloud חשבון שירות

לשרת proxy יכול להיות רק Google Cloud חשבון שירות אחד. אם כמה לקוחות משתמשים באותו proxy, הם צריכים להשתמש באותו חשבון שירות. חשוב לנקוט משנה זהירות כשמשתפים חשבון שירות עם כמה לקוחות, מהסיבות הבאות:

  • כדי לקרוא את נתוני FHIR ב-Cloud Healthcare API, לחשבון השירות יש הרשאות קריאה וכתיבה רחבות.

  • כתובת האימייל של הגורם המבצע ביומני הביקורת של Cloud מקושרת לחשבון השירות.

    לדוגמה, אם אתם קוראים ל-Cloud Healthcare API באמצעות חשבון Google שלכם לאימות, יומני הביקורת של Cloud ירשמו את כתובת האימייל שלכם ככתובת האימייל העיקרית. כשמשתמשים בשרת proxy כדי לבצע קריאה ל-Cloud Healthcare API, ה-proxy משתמש בחשבון השירות שלו, וכתובת האימייל של חשבון השירות היא כתובת האימייל העיקרית, כך שהמתקשר המקורי מוסתר. כדי לשמור את משתמש הקצה במטא-נתונים של יומן הביקורת, צריך להעביר את כתובת האימייל של משתמש הקצה בשדה sub של אסימון ה-JWT.

הגדרת מאגר FHIR

אין צורך להגדיר את מאגר ה-FHIR שמכיל את נתוני ה-FHIR שאתם ניגשים אליהם.

שליחת בקשות SMART on FHIR

בקטע הזה מוסבר על השיטות הנתמכות של SMART on FHIR ב-Cloud Healthcare API ואיך נאכפת הגישה למשאבים כששולחים בקשת SMART on FHIR.

כשמבצעים בקשה, שרת ההרשאות אחראי ליצירת טוקנים של גישה עם היקף ההרשאות הרלוונטי של SMART והקשר ההפעלה.

אמצעי התשלום הנתמכים

‫Cloud Healthcare API תומך ב-SMART on FHIR בכל השיטות של projects.locations.datasets.fhirStores.fhir, מלבד השיטות הבאות:

אכיפת גישה למשאבים

כששולחים בקשת SMART on FHIR למאגר FHIR, בקרת הגישה מתבצעת בסדר הבא:

  1. ממשק Cloud Healthcare API בודק את ההרשאות בחשבון השירות שהוגדר בשרת ה-proxy. Google Cloudאם לחשבון השירות יש את הרשאות ה-IAM הנכונות במאגר FHIR, הבקשה תמשיך.
  2. ‫Cloud Healthcare API בודק אם לאסימון SMART יש את ההרשאות המתאימות לגישה לכל משאב FHIR שהבקשה מתייחסת אליו.

תא המטופל הוא קריטי ללוגיקה של אכיפת הגישה ב-Cloud Healthcare API. ב-SMART on FHIR יש רשימה של סוגי משאבים של FHIR שאפשר לכלול בתא של מטופל. לסוגי המשאבים יש גם קריטריונים משלהם להכללה. בהמשך הקטע הזה, סוגי המשאבים שעומדים בדרישות נקראים "סוגי משאבים שעומדים בדרישות של חלוקה למחלקות של מטופלים". סוגי משאבים שלא עומדים בדרישות נקראים 'סוגי משאבים שלא עומדים בדרישות של תא מטופל'.

בקשות SMART on FHIR למאגר FHIR צריכות לעמוד בדרישות הבאות:

  • מציינים את התפקיד patient, user או system בהיקפי ההרשאות של SMART. אם אתם מקצים את התפקיד patient, אתם צריכים לספק הקשר של מטופל. ההקשר של המטופל הוא מזהה לוגי של משאב Patient. משאב המטופל צריך כבר להיות קיים במאגר FHIR או להתקיים אחרי שליחת הבקשה, אחרת Cloud Healthcare API דוחה את הבקשה.

  • כשיוצרים, קוראים, מעדכנים או מוחקים משאב, הערך של resourceType וסוג הפעולה (read או write) צריכים להיות זהים, אחרת Cloud Healthcare API דוחה את הבקשה.

  • אם מספקים היקף patient שמכיל סוגי משאבים שלא עומדים בדרישות של חלוקה למחלקות של מטופלים, כמו patient/Practitioner.*, בדיקת האימות של ההיקף תיכשל ו-Cloud Healthcare API ידחה את ההיקף.

  • אפשר להגדיר את כל סוגי המשאבים באמצעות ההיקף user. אם יש הקשר של מטופל עם היקף user, סוגי משאבים שעומדים בדרישות של תא מטופל מוגבלים להקשר של המטופל. סוגי המשאבים הנותרים מתעלמים מההקשר של המטופל.

  • אם יש הקשר של מטופל, סוגי המשאבים שעומדים בדרישות לתא המטופל מוגבלים למטופל הנתון. לדוגמה, כדי שמשאב Observation יהיה נגיש, השדה subject שלו צריך להפנות למשאב Patient שצוין. במאמר Resource CompartmentDefinition - Content מופיעה רשימה של השדות בכל סוג משאב של תא מטופל שצריך להפנות אליהם את המטופל הנתון כדי שהמשאב ייחשב כמשאב שנמצא בתוך תא המטופל.

  • בקשות יכולות להכיל גם את היקף ההרשאות patient וגם את היקף ההרשאות user.

  • אל תשתמשו בהיקף system עם הקשר המטופל, אחרת הבקשה תיכשל.

  • אל תשתמשו בהיקף system עם ההיקף patient או עם ההיקף user.

  • אם קוראים לשיטה שמקבלת גישה למספר משאבים (לדוגמה, השיטה fhir.Patient-everything, fhir.executeBundle או fhir.search), בקרת הגישה חלה על כל משאב בנפרד.