Lansarea aplicațiilor SMART explicată: scopuri, lansare, PKCE

Răspuns scurt: SMART App Launch (SMART on FHIR) este specificația HL7 pentru modul în care o aplicație obține acces autorizat la un server FHIR în numele unui utilizator. Este OAuth 2.0 și OpenID Connect cu convenții specifice FHIR: un document de descoperire la .well-known/smart-configuration; două moduri de lansare (lansare EHR, unde EHR-ul deschide aplicația în contextul pacientului curent și lansare independentă, unde utilizatorul deschide aplicația și alege un pacient); domenii (scopes) într-o sintaxă compatibilă cu FHIR (patient/Observation.rs înseamnă citire și căutare a observațiilor pacientului în context); context de lansare returnat odată cu token-ul (ce pacient, ce consultație); și servicii backend pentru acces de la sistem la sistem cu autentificare client JWT semnat. SMART v2 (din 2021) a făcut PKCE obligatoriu, a adăugat domenii granulare și autentificare client asimetrică și este versiunea cerută de programele naționale.

Pasul 1: Descoperire

Descoperirea SMART App Launch începe cu aplicația care preia documentul .well-known/smart-configuration al serverului FHIR, care listează punctele finale de autorizare și token, capabilitățile suportate (lansare EHR, lansare independentă, clienți publici și confidențiali, OpenID Connect, permisiuni pentru pacient și utilizator), domeniile suportate, metodele de provocare a codului PKCE și tipurile de acordare, astfel încât aplicația să știe unde să trimită utilizatorul.

GET https://fhir.example-hospital.org/.well-known/smart-configuration

{
  "issuer": "https://auth.example-hospital.org",
  "authorization_endpoint": "https://auth.example-hospital.org/authorize",
  "token_endpoint": "https://auth.example-hospital.org/token",
  "introspection_endpoint": "https://auth.example-hospital.org/introspect",
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "client_credentials"]
}

Aplicația află unde să trimită utilizatorul și ce suportă serverul.

Pasul 2: Lansare

SMART App Launch are două moduri de lansare. Într-o lansare EHR, clinicianul deschide aplicația în cadrul EHR, care transmite un parametru iss (serverul FHIR) și un token de lansare opac care codifică pacientul și întâlnirea curentă. Într-o lansare independentă, utilizatorul deschide aplicația direct, iar serverul de autorizare îi cere să aleagă sau să confirme un pacient.

Lansare EHR. Medicul dă clic pe aplicație în cadrul EHR-ului; EHR-ul deschide URL-ul de lansare al aplicației cu doi parametri: iss (serverul FHIR) și launch (un token opac care codifică pacientul și consultația curentă). Aplicația trebuie să repete launch în cererea sa de autorizare cu domeniul launch.

Lansare independentă. Utilizatorul deschide aplicația direct; aplicația cunoaște serverul FHIR (ales sau configurat) și cere context cu launch/patient; serverul de autorizare cere utilizatorului să aleagă sau să confirme un pacient.

Pasul 3: Cod de autorizare cu PKCE

Pasul de autorizare SMART este fluxul de autorizare OAuth 2.0 cu PKCE: aplicația trimite utilizatorul către punctul final de autorizare cu domeniile sale, aud-ul serverului FHIR și o provocare de cod; utilizatorul se autentifică și aprobă; aplicația schimbă codul returnat și verificatorul de cod pentru un token de acces care ajunge împreună cu contextul de lansare.

GET https://auth.example-hospital.org/authorize?
  response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
  &scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
  &state=af0ifjsldkj&aud=https://fhir.example-hospital.org
  &launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

Utilizatorul se autentifică (cu furnizorul de identitate al spitalului) și aprobă domeniile; serverul redirecționează înapoi cu un code; aplicația îl schimbă:

POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
  "refresh_token": "a8c3...",
  "id_token": "eyJhbGciOi...",
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "fhirUser": "Practitioner/42",
  "need_patient_banner": true,
  "smart_style_url": "https://ehr.example.org/styles/smart.json"
}

Contextul de lansare (patient, encounter, fhirUser) ajunge alături de token. Clienții publici (aplicații mobile și de browser) folosesc PKCE și nu au secret de client; clienții confidențiali se autentifică cu un secret sau, preferabil, cu un JWT semnat (private_key_jwt) prin metoda asimetrică.

Domenii (Scopes)

Domeniile SMART on FHIR v2 folosesc sintaxa context/resursă.permisiuni, unde contextul este pacient, utilizator sau sistem, iar permisiunile combină c, r, u, d și s pentru creare, citire, actualizare, ștergere și căutare, ca în pacient/Observation.rs. Domeniile granulare adaugă un filtru, openid și fhirUser oferă identitatea utilizatorului, domeniile de lansare solicită context, iar offline_access solicită un token de reîmprospătare.

Sintaxa SMART v2: <context>/<resource>.<permissions> unde contextul este patient (pacientul în context), user (ceea ce poate vedea utilizatorul) sau system (backend), iar permisiunile sunt oricare dintre c create, r read, u update, d delete, s search, în această ordine: patient/Observation.rs, user/Patient.rs, system/*.cruds. Domeniile granulare adaugă un filtru: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser oferă un ID token și identitatea FHIR a utilizatorului; launch, launch/patient, launch/encounter cer context; offline_access un refresh token pentru utilizare când utilizatorul este plecat, online_access unul valabil doar în timpul sesiunii. Sintaxa v1 (patient/Observation.read) este încă acceptată de multe servere.

Servicii Backend

Pentru un sistem care acționează fără un utilizator (un export nocturn, un motor de integrare), SMART Backend Services folosește client_credentials cu o aserțiune JWT semnată (cheile publice ale clientului publicate la un URL JWKS) și domenii system/. Fără utilizator, fără context de lansare, înregistrare strictă.

Rularea în siguranță

Rularea SMART App Launch în siguranță înseamnă înregistrarea exactă a URI-urilor de redirecționare, neutilizarea niciodată a fluxului implicit, stocarea și rotirea sigură a tokenurilor de reîmprospătare, validarea stării și a aud-ului tokenurilor ID, verificarea tokenurilor la fiecare apel API, impunerea atât a domeniilor, cât și a contextului pacientului la nivelul datelor, astfel încât un token pentru un pacient să nu citească niciodată altul, și înregistrarea fiecărui acces.

Înregistrați URI-uri de redirecționare exacte; nu folosiți niciodată fluxul implicit; stocați refresh token-urile în siguranță și rotiți-le; validați state; verificați aud al ID token-urilor; verificați token-urile la fiecare apel API (introspecție sau validare JWT) și impuneți domeniile și contextul pacientului la nivelul datelor, deoarece un token pentru Patient/123 nu trebuie să citească niciodată Patient/124; înregistrați fiecare acces (Securitate și identitate: harta). SMART definește, de asemenea, Marcaje de Acces pentru Pacienți (Patient Access Brands), o modalitate prin care aplicațiile arată utilizatorilor la ce organizații se pot conecta și interoperează cu SMART Health Links pentru partajarea inițiată de pacient.

Unde este necesar

Regulile de acces pentru pacienți din SUA cer EHR-urilor certificate să suporte SMART App Launch și Backend Services; programele naționale din Europa îl adoptă pentru accesul aplicațiilor (MedMij din Olanda folosește OAuth 2.0 cu convenții echivalente); IPS și multe ghiduri de implementare îl presupun. Vezi TEFCA și Sisteme naționale de sănătate electronică.

În Anpheros

Anpheros Platform folosește OAuth 2.0 cu PKCE pentru aplicații și autentificare client JWT semnat pentru backend-uri, cu domenii derivate din consimțământul persoanei și contextul pacientului impus la fiecare cerere. Site-ul dezvoltatorului documentează autentificarea și modelul backend SMART on FHIR pentru a construi pe baza sa.

Pagini conexe

Surse

Întrebări frecvente

SMART on FHIR este același lucru cu OAuth 2.0?

Este OAuth 2.0 și OpenID Connect cu adăugiri specifice FHIR: descoperire, context de lansare, sintaxa domeniilor și servicii backend. Orice bibliotecă OAuth funcționează; convențiile SMART sunt cele care fac o aplicație portabilă pe servere FHIR.

Am nevoie de PKCE pentru o aplicație server-side?

În SMART v2, da, pentru toți clienții care folosesc fluxul de cod de autorizare. Clienții confidențiali adaugă autentificarea clientului (un secret sau un JWT semnat) deasupra.

Care este diferența dintre domeniile patient/ și user/?

patient/ limitează accesul la un singur pacient din contextul de lansare; user/ acordă acces la ceea ce este permis utilizatorului autentificat să vadă, indiferent de pacient. Aplicațiile orientate către pacienți folosesc patient/; aplicațiile pentru medici folosesc adesea user/ cu context.

Poate o aplicație SMART să scrie în dosar?

Dacă i se acordă permisiuni de creare sau actualizare (c, u) în domeniile sale și serverul permite acest lucru. Multe implementări acordă aplicațiilor pentru pacienți doar permisiuni de citire și căutare și direcționează scrierile prin resurse specifice, cum ar fi QuestionnaireResponse.

Anpheros Platform

Încearcă gratuit în sandbox

Primul apel FHIR în 5 minute. Un API HL7 FHIR R4 cu consimțământul pacientului integrat: încearcă-l în sandbox, apoi conectează-ți propria aplicație sau sistemul clinicii.

Creează un sandbox gratuit Pornește aplicația demo →Cod de pornire (Python) →Colecția Postman →Citește ghidurile pentru dezvoltatori →

Gratuit · 30 de pacienți sintetici · fără card

Acest ghid este informativ și nu înlocuiește consultul medical. Pentru decizii despre sănătatea ta, vorbește cu medicul tău. În caz de urgență, sună la numărul de urgență local (112 în Europa).

Scris de

Echipa Anpheros

Anpheros construiește un dosar medical pe care pacientul îl controlează și îl poate da oricărei clinici, pe o platformă HL7 FHIR R4, cu sediul în UE. Ghidurile te ajută să-ți înțelegi și să-ți organizezi sănătatea; nu înlocuiesc medicul.

Despre Anpheros →