Implementasjonsguide SMART App Launch Framework

 

Innholdsfortegnelse

Introduksjon

SMART sørger for en pålitelig og sikker autorisasjonsprotokoll for en rekke applikasjonsarkitekturer og kan benyttes for å støtte oppunder applikasjoner som benyttes av klinikere og/eller pasienter.

SMART gir tredjepartsapplikasjoner autorisert tilgang til data i elektroniske pasientjournaler via en pålitelig og sikker autorisasjonsprotokoll. Applikasjonene kan starte som en del av eller utenfor brukergrensesnittet til et EPJ-system. Rammeverket støtter per i dag fire bruksscenarioer beskrevet i Argonaut prosjektets fase 1. Argonaut prosjektet tar for seg følgende bruksscenarioer:

  1. Applikasjoner for pasienter som kan starte frittstående

  2. Applikasjoner for pasienter som kan starte fra en portal

  3. Applikasjoner for klinikere som kan starte frittstående

  4. Applikasjoner for klinikere som kan starte i en EPJ eller portal

Dette dokumentet vil kun gå i detalj på bruksscenario 4.

SMART benyttet sammen med FHIR beskrives som SMART on FHIR og beskriver to deler, en autorisasjonsprotokoll basert på OAuth der en web-applikasjon registrert som klient i en EPJ gis autorisert tilgang til lokale helsedata. I tillegg vises det til spesifikasjonen og den voksende standarden FHIR som beskriver ett sett med ressurser og interaksjoner for å utveksle data.

Formål med dokumentet, målgruppe og avgrensning

Formål

Formålet med dokumentet er å tydeliggjøre premisser for teknisk tilrettelegging av EPJ for SMART App Launch Framework.

Målgruppe

Målgruppen for dokumentet er tekniske ressurser, testpersonell og prosjektledelse med ansvar for å tilrettelegge EPJ for SMART App Launch Framework.

Avgrensning

Dokumentet er avgrenset til de tjenestene og behovene som skal understøtte en implementasjon av SMART App Launch Framework for bruksscenario 4 beskrevet i introduksjonen av dokumentet.

Dokumentet omfatter ikke

  • etablering av driftsrutiner

  • etablering av overvåkningsrutiner

Definisjoner

  • Helsepersonell – en person autorisert som helsepersonell i henhold til helsepersonelloven § 48. Rettighetene til ulike autorisasjoner er forskjellig, f.eks. kan kun leger verifisere kritisk informasjon.

  • Innbygger – en person som bor innen et spesifikt område. Et område her kan for eksempel være et land, fylke, kommune, by og sted.

  • Pasient – en person som får behandling av helsepersonell for psykisk og/eller fysisk sykdom/lidelse eller skade, på sykehus/klinikk og/eller andre behandlingsinstitusjoner.

  • EPJ – Elektronisk pasientjournal

  • EHR – Electronic Health Record

  • SMART – Substitutable Medical Applications

  • FHIR – Fast Healthcare Interoperability Resources

  • SMART App Launch Framework – Standardbasert applikasjonplattform for elektroniske pasientjournaler

  • Tilgangstoken – Akkreditiver benyttet for å aksessere beskyttede ressurser, se seksjon 1.4 i RFC6749

  • Autorisasjonskode – En kode som tilegnes i forbindelse med autorization code grant flyten, denne benyttes til å tilegne seg et tilgangstoken, se seksjon 1.3 og 1.3.1 i RFC6749

  • Refresh token – Akkreditiver benyttet for å tilegne seg et nytt tilgangstoken når det gjeldende tilgangstokenet utgår på tid eller blir ugyldig, seksjon 1.5 i RFC6749

Løsningsbeskrivelse

SMART App Launch Framework

A. Integrert nettleser for å starte webapplikasjon

EPJ benytter integrert nettleser for å starte en webapplikasjon med SMART App Launch Framework-støtte

B. LaunchContext opprettes

EPJ oppretter en LaunchContext som tildeles en unik identifikator og assosieres med client_id for SMART-applikasjonen. Konteksten består av:

Parametere

Parametere

patient

Påkrevet

Den logiske logiske ressursidentifikatoren for pasienten

practitioner

valgfri

Den logiske ressursidentifikatoren for helsepersonellet som benytter applikasjonen

encounter

valgfri

Den logiske ressursidentifikatoren for konsultasjonen

C. Launch-sekvensen initieres

I praksis er dette en URL til webapplikasjonen. Eksempel: Location: https://app/launch?iss=https%3A%2F%2Fehr%2Ffhir&launch=xyz1

Parametere

Parametere

iss

Påkrevet

Identifiserer EPJens FHIR endepunkt. Web-applikasjonen benytter dette endepunktet for å skaffe ytterligere detaljer EPJen, inkludert URLen til autorisasjonserveren

launch

Påkrevet

Ikke-transparent identifikator for denne spesifikke oppstartsekvensen. Dette parameteret skal kommuniseres tilbake til EPJen på autorisasjonstidspunktet og legges ved som et launch-parameter (se eksempel ovenfor).

D. Applikasjonen mottar launch-notifikasjon

Ved mottak av launch-notifikasjonen skal applikasjonen forespørre utstederen (iss) sitt /metadata/ endepunkt eller .well-known/smart-configuration.json endepunkt som inneholder URLene til EPJen sitt  authorize og token endepunkt.

E. Applikasjonen utfører en forespørsel mot authorize endepunktet

Applikasjonen skal deretter gjøre en forespørsel mot authorize endepunktet med følgende parametere:

Parametere

Parametere

response_type

Påkrevet

Fiksert verdi code.

client_id

Påkrevet

Klientens identifikator.

redirect_uri

Påkrevet

Må samsvare med en av de forhåndsregistrerte redirect URLene for klienten.

launch

Påkrevet

Må samsvare med den mottatte launch-parameteren fra EPJ.

scope

Påkrevet

Applikasjonen angir ved hjelp av parameteren scope hvilken aksess den trenger til helsedata. Dette inkluderer kliniske scope som patient/*.read, openid, fhirUser, samt et launch scope som indikerer at applikasjonen ønsker den allerede etablerte launch-konteksten fra EPJen.

state

Påkrevet

Ikke-transparent verdi satt av klienten for å opprettholde tilstanden mellom forespørsel og responsen. Autorisasjonsserveren inkluderer verdien når den dirigerer nettleseren tilbake til klienten. Parameteren skal benyttes for å forhindre cross-site request forgery og session fixation attacks.

aud

Påkrevet

URL til EPJen sin ressursserver (FHIR-endepunkt). Denne parameteren skal motvirke lekkasje av genuine bearer tokens til en falsk ressursserver. I kontekst av gjeldende bruksscenario skal verdien i aud parameteren være den samme som var satt i iss parameteren.



Applikasjonen skal bruke en uforutsigbar verdi for state parameteren med minimum 122 bit entropi, en korrekt konfigurert tilfeldig uuid vil dermed være egnet. Applikasjonen skal deretter validere verdien av state parameteren ved mottak til redirect URL endepunktet og skal sikre at verdien er bundet opp mot brukerens gjeldende sesjon, for eksempel ved å relatere verdien til en sesjonsidentifikator utstedt av applikasjonen. Applikasjonen burde begrense tilgangsnivå og tidsperiode til det absolutte minimum.

Dersom applikasjonen trenger å autentisere identiteten til brukeren skal den inkludere to OpenID Connect scope: openid og fhirUser. Når applikasjonen forespør disse to scopene, og forespørselen godkjennes vil applikasjonen motta et id_token i tillegg til et tilgangstoken. Se seksjonen SMART launch kontekst parametere.

Som et eksempel på hvilke scope en applikasjon vil kunne be om la oss anta at en applikasjon trenger demografi og observasjoner for en pasient, i tillegg til informasjon om innlogget bruker kan applikasjonen be om:

  • patient/Patient.read

  • patient/Observation.read

  • openid fhirUser

For bruksscenario 4 som denne implementasjonsguiden fokuserer på skal applikasjonen alltid angi scopet launch og URL-parameteren launch={launch_id}, launch_id er den samme verdien som applikasjonen mottok i steg C og denne vil bli assosiert med EPJens kontekst for denne launch-notifikasjonen.

En typisk URL til authorize endepunktet vil se slik ut:

1 2 3 4 5 6 7 8 Location: https://ehr/authorize? response_type=code& client_id=app-client-id& redirect_uri=https%3A%2F%2Fapp%2Fafter-auth& launch=xyz123& scope=launch+patient%2FObservation.read+patient%2FPatient.read+openid+fhirUser& state=98wrghuwuogerg97& aud=https://ehr/fhir

Autorisasjonen avgjøres av EPJens autorisasjonsserver som potensielt kan kreve at sluttbrukeren samtykker til autorisasjonen. Autorisasjonsserveren håndhever tilgangsregler basert på lokale tilgangsregler og ev. input fra sluttbruker. EPJen avgjør til slutt om applikasjonen skal tillates eller nektes tilgang. Avgjørelsen kommuniseres tilbake til applikasjonen ved at EPJens autorisasjonsserver godkjenner forespørselen og returnerer en autorisasjonskode, eller nekter tilgang og returner en feilkode/-respons, se seksjon 4.1.2.1 i RFC6749. Autorisasjonskoder har kort levetid, vanligvis utløper de i løpet av ett minutt. Koden sendes til applikasjonen når EPJens autorisasjonsserver navigerer til applikasjonens redirect_uri med følgende parametere:

Parametere

Parametere

code

Påkrevet

Autorisasjonskoden generert av autorisasjonsserveren. Autorisasjonskoden skal utløpe kort tid etter at den er utstedt for å begrense risikoen for lekkasjer

state

Påkrevet

Eksakt verdi slik den var mottatt fra klienten

 

Basert på client_id, gjeldende EPJ-bruker, konfigurerte tilgangsregler, og ev. direkte input fra brukeren vil EPJen godkjenne eller avvise forespørselen. Denne avgjørelsen kommuniseres tilbake til applikasjonen ved å navigere nettleseren til applikasjonens registrerte redirect_uri:

1 2 3 Location: https://app/after-auth? code=123abc& state=98wrghuwuogerg97

F. Applikasjonen veksler inn autorisasjonskoden i et tilgangstoken

Etter at applikasjonen har mottatt en autorisasjonskode veksles denne inn i et tilgangstoken via et HTTP POST kall til EPJens autorisasjonsserver token-endepunkt, nødvendige parametere legges ved som innhold i forespørslen og content-type settes til application/x-www-form-urlencoded som beskrevet i seksjon 4.1.3 av RFC6749.

For såkalte public apps er autentisering ikke mulig siden klienten mangler en secret og kan derfor ikke bevise sin identitet når den utfører et kall. Ende-til-ende systemet kan fortsatt være sikkert siden klienten aksesseres fra et kjent HTTPS beskyttet endepunkt håndhevet av redirect_uri parameteret i konfigurasjonen. For såkalte confidential apps er det påkrevet å sette en Authorization header som benytter HTTP Basic authentication, brukernavnet vil være applikasjonens client_id og passordet er applikasjonens client_secret, se eksempel.

Parametere

Parametere

grant_type

Påkrevet

Fiksert verdi: authorization_code

code

Påkrevet

Autorisasjonskoden applikasjonen mottok fra autorisasjonsserveren sitt authorization-endepunkt

redirect_uri

Påkrevet

Den samme redirect_uri som ble benyttet i den initiale autorisasjonsforespørslen

client_id

betinget

Påkrevet for public apps, utelates for confidential apps

EPJens autorisasjonsserver skal returnere  et JSON-objekt som inkluderer et tilgangstoken eller en beskjed som indikerer at tilgangsforespørslen ikke ble godkjent. JSON-strukturen inkluderer følgende parametere:

Parametere

Parametere

access_token

Påkrevet

Tilgangstoken utstedt av autorisasjonsserveren

token_type

Påkrevet

Fiksert verdi: bearer

expires_in

anbefales

Tilgangstokenet sin levetid i sekunder, etter dette vil tilgangstokenet ikke bli akseptert av ressursserveren

scope

Påkrevet

Aksesstilgang som er autorisert, legg merke til at dette kan være forskjellig fra det som applikasjonen initialt ba om

id_token

valgfri

Dersom forespurt inneholder informasjon om pålogget bruker

refresh_token

valgfri

Et token som kan benyttes til å forespørre autorisasjonsserveren om et nytt tilgangstoken med det samme nivået eller subsett av den opprinnelige autorisasjonstildelingen

Dersom applikasjonen startes i en pasientkontekst skal parametere for å kommunisere kontekstverdiene inkluderes. For eksempel en parameter som "patient": "123" indikerer FHIR ressursen https://ehr/fhir/Patient/123. Andre kontekstparametere kan også inkluderes, for utfyllende detaljer se SMART launch context parameters.

Parameterne for kontekstverdiene inkluderes som en del av innholdet i HTTP-responsen fra token-endepunktet som beskrevet i seksjon 5.1 av RFC6749.

Autorisasjonsserveren response skal inkludere en HTTP Cache-Control respons header med verdien no-store, i tillegg til en Pragma respons header med verdien no-cache.

Eksempel på respons fra token-endepunktet:

1 2 3 4 5 6 7 8 9 { "access_token": "i8hweunweunweofiwweoijewiwe", "token_type": "bearer", "expires_in": 3600, "scope": "patient/Observation.read patient/Patient.read", "intent": "client-ui-name", "patient": "123", "encounter": "456" }

G. Applikasjonen har nå tilgang til helsedata

Applikasjonen har nå tilgang til helsedata via det mottatte tilgangstoken.

Med et gyldig tilgangstoken har applikasjonen tilgang til beskyttede helsedata i EPJ ved å gjøre forespørsler mot EPJen sitt tilhørende FHIR API. Alle forespørsler til FHIR APIet må inkludere en Authorization header som representerer access_token som et "Bearer" token:

1 Authorization: Bearer {{access_token}}

Med hjelp fra kontekstparametrene fra responsen F. vet applikasjonen hvilken pasient som er en del av konteksten og har et OAuth Bearer tilgangstoken som kan brukes til å hente ut helsedata:

Eksepempel på forespørsel:

1 2 GET https://ehr/fhir/Patient/123 Authorization: Bearer i8hweunweunweofiwweoijewiwe

Eksempel på respons:

1 2 3 4 { "resourceType": "Patient", "birthTime": ... }

Eksempel med komplett payload

Scopes og Launch Context

SMART App Launch Framework benytter OAuth scopes for å kommunisere og forhandle krav til tilgang. I tillegg til hvilke scope som er satt i tilgangstokenet er tilgang i tillegg begrenset til de privilegiene eller autorisasjonen brukeren har tilgang til. Generelt benyttes scopes for tre typer data:

  1. Kliniske data

  2. Kontekstuelle data

  3. Identitetsdata

Enkel oversikt over de mest brukte scopene:

Scope

Tilgang

Scope Type

Scope

Tilgang

Scope Type

patient/*.read

Tilgang til å lese en hvilken som helst ressurs for den gjeldende pasienten

Kliniske data

user/*.*

Tilgang til å lese og skrive til alle ressurser den gjeldende brukeren har tilgang til

Kliniske data

openid fhirUser (ev. openid profile)

Tilgang til å motta informasjon om den gjeldende innloggede brukeren

Identitetsdata

launch

Tilgang til å motta en launch context når applikasjonen er startet fra en EPJ

Kontekstuelle data

launch/patient

Når applikasjonen starter utenfor konteksten av en EPJ, be om å velge en pasient ved oppstart

Kontekstuelle data

offline_access

Be om en refresh_token som kan benyttes til å motta et nytt tilgangstoken, også etter at endebruker ikke lenger er innlogget

-

online_access

Be om en refresh_token som kan benyttes til å motta et nytt tilgangstoken, og som vil være brukbar så lenge endebruker er pålogget

-

Scopes for å kunne forespørre kliniske data

SMART App Launch Framework-spesifikasjonen definerer OAuth scopes som korresponderer direkte med FHIR ressurstyper, samt lese (read) og skrive (write) tilgang for pasientspesifikke eller brukernivå aksess. Applikasjoner som trenger leseaksess til data i EPJ (lese- og søkeinteraksjoner) skal be om lese (read) scope. Applikasjoner som trenger å kunne skrive data til en EPJ, FHIR-interaksjonen create, update, delete, skal be om skrive (write) scope.

Klinisk scope-syntaks

1 clinical-scope ::= ( 'patient' | 'user' ) '/' ( fhir-resource | '*' ) '.' ( 'read' | 'write' | '*' )`

Pasientspesifikke scope

Pasientspesifikke scope gir tilgang til data om en enkelt pasient. Hvilken pasient dette måtte være er ikke spesifisert her, kliniske scope omhandler hva ikke hvem. Pasientspesifikke scope innehar formen: patient/:resourceType.(read|write|*).

Eksempler på pasientspesifikke scope:

Mål

Scope

Kommentar

Mål

Scope

Kommentar

Lese alle observasjoner tilhørende en pasient

patient/Observation.read



Lese alle demografiske data om en pasient

patient/Patient.read

Noter forskjellen i kapitalisering mellom "patient", tilgangstype, og "Patient", ressurs

Lagre en ny blodtrykksmåling for en pasient

patient/Observation.write

Noter at med dette scopet kan en applikasjon ikke bare lagre blodtrykk, men også andre typer observasjoner. NB: skrivetilgang (write) impliserer ikke lesetilgang (read)

Les alle tilgjengelige data for en pasient

patient/*.read



Brukernivå scope

Brukernivå scope gir tilgang til data som brukeren kan aksessere. Dette omhandler ikke kun data om brukeren, men data som er tilgjengelig for brukeren. Brukernivå scope innehar formen: user/:resourceType(read|write|*).

Eksempler på brukernivå scope:

Mål

Scope

Kommentar

Mål

Scope

Kommentar

Lese en oversikt over lab-observasjoner på tvers av pasienter

user/Observation.read



Håndtere alle avtaler/timeavtaler som den autoriserte brukeren har tilgang til

user/Appointment.read user/Appointment.write

Legg merke til at både read og write må begge være angitt (skrivetilgang impliserer ikke lesetilgang)

Håndtere alle ressurser som den autoriserte brukeren har tilgang til

user/*.read user/*write



Kunne velge en pasient

user/Patient.read

Tillater applikasjonen å velge en pasient

Scopes for å kunne forespørre om kontekstuelle data

Mange applikasjoner baserer seg på kontekstuelle data fra EPJen som:

  • Hvilken pasientjournal er "åpen" i EPJ i denne kontekst?

  • Hvilken konsultasjon/møte er "åpen" i EPJ i denne kontekst?

  • På hvilket behandlingssted befinner gjeldende helsepersonell seg i denne kontekst?

For å kunne svare ut slike detaljer kan en applikasjon be om launch-kontekst scope i tillegg til kliniske scope. I det bruksscenarioet som denne implementasjonsguiden beskriver er det kun scopet launch som kan benyttes. For mer informasjon 3.1 Apps that launch from the EHR.

Scopes for å kunne forespørre om identitetsdata

Applikasjoner som trenger å autentisere helsepersonellet kan benytte OpenID Connect scopene: openid og fhirUser. Når forespørslen om disse scopene innvilges mottar applikasjonen en id_token som en del av token-responsen. For mer informasjon 4. Scopes for requesting identity data.

Sikkerhet

Generelle sikkerhetsvurderinger

De som implementerer SMART App Launch Framework må være oppmerksom på krav til sikkerhet og gjennomføre en vurdering av risiko og sikkerhet innenfor flere områder før SMART App Launch Framework etableres.

Ved tilkobling til helsenettet binder man seg til Normens krav til informasjonssikkerhet. Selv om det er ikke er et krav om at SMART App Launch Framework tilbys via helsenettet, BURDE en tilbyder av SMART App Launch Framework vurdere sikkerhetskravene som er definert i Normen.

I tillegg til dette har Direktoratet for e-helse utgitt referansearkitekturer for datadeling og dokumentdeling. Under er det kort beskrevet noen områder og krav, men hver implementasjon må vurdere sikkerheten ved sin egen implementasjon.

Juridisk / Avtale

Ved etablering av SMART App Launch Framework SKAL det vurderes hvilke juridiske og avtalemessige krav som gjelder basert på informasjonen som tilbys. Dette kan inkludere databehandleravtaler eller andre juridiske krav for etablering av SMART App Launch Framework.

Krav til risikovurderinger

Ved etablering av SMART App Launch Framework SKAL det gjennomføres en risikovurdering, og denne skal dokumenteres for senere revisjon ved behov

Sikring av kommunikasjonen

Det er viktig at generell HTTP sikkerhet implementeres og det SKAL benyttes TLS eller annet transportsikring ved overføring av informasjon. Direktoratet for e-helse har utgitt en referansearkitektur for datadeling som burde vurderes.

Autentisering

Klienten og bruker som gis tilgang SKAL autentiseres.

Logging / Audit

Det SKAL logges nok informasjon slik at det i etterkant er mulig å verifisere tilgangsbeslutningen.

Refresh token

Dersom applikasjonen mottar et refresh token sammen med et tilgangstoken kan den bruke dette refresh token for å hente ut et nytt tilgangstoken med samme tilgangsnivå når tilgangstokenet utløper. Et refresh token SKAL være bundet mot den samme client_id og SKAL ha det samme eller et subsett av tilgangsnivåene som tilgangstokenet den er assosiert med.

Lagring av tilgangstoken klientside

Applikasjoner BURDE lagre tokens den mottar i applikasjonspesifikke lagringslokasjoner, ikke systemtilgjengelige lokasjoner.