View a markdown version of this page

SMART su ambiti FHIR OAuth 2.0 supportati da HealthLake - AWS HealthLake
Ambito di lancio autonomoAmbiti di risorse SMART su FHIR per HealthLake

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

SMART su ambiti FHIR OAuth 2.0 supportati da HealthLake

HealthLake utilizza OAuth 2.0 come protocollo di autorizzazione. L'utilizzo di questo protocollo sul server di autorizzazione consente di definire le autorizzazioni dell'archivio HealthLake dati (creazione, lettura, aggiornamento, eliminazione e ricerca) per le risorse FHIR a cui un'applicazione client ha accesso.

Il framework SMART on FHIR definisce un set di ambiti che possono essere richiesti al server di autorizzazione. Ad esempio, un'applicazione client progettata esclusivamente per consentire ai pazienti di visualizzare i risultati di laboratorio o visualizzare i propri dati di contatto dovrebbe essere autorizzata solo a richiedere read gli oscilloscopi.

Nota

HealthLake fornisce supporto sia per SMART su FHIR V1 che V2, come descritto di seguito. SMART su FHIR AuthorizationStrategyè impostato su uno dei tre valori seguenti al momento della creazione del data store:

  • SMART_ON_FHIR_V1— Supporto solo per SMART su FHIR V1, che include le autorizzazioni read (read/search) e write (create/update/delete).

  • SMART_ON_FHIR— Supporto per SMART su FHIR V1 e V2, che include,create, read updatedelete, e autorizzazioni. search

  • AWS_AUTH— La strategia di AWS HealthLake autorizzazione predefinita; non affiliata a SMART su FHIR.

Ambito di lancio autonomo

HealthLake supporta l'ambito della modalità di avvio autonoma. launch/patient

In modalità di avvio autonoma, un'applicazione client richiede l'accesso ai dati clinici del paziente perché l'utente e il paziente non sono noti all'applicazione client. Pertanto, la richiesta di autorizzazione dell'applicazione client richiede esplicitamente la restituzione dell'ambito del paziente. Una volta completata con successo l'autenticazione, il server di autorizzazione emette un token di accesso contenente l'ambito del paziente di avvio richiesto. Il contesto paziente necessario viene fornito insieme al token di accesso nella risposta del server di autorizzazione.

Ambiti della modalità di avvio supportati
Scope Description

launch/patient

Un parametro in una richiesta di autorizzazione OAuth 2.0 che richiede la restituzione dei dati del paziente nella risposta di autorizzazione.

Ambiti di risorse SMART su FHIR per HealthLake

HealthLake definisce tre livelli di SMART sugli ambiti di risorse FHIR.

  • patientgli ambiti garantiscono l'accesso a dati specifici su un singolo paziente.

  • usergli ambiti garantiscono l'accesso a dati specifici a cui un utente può accedere.

  • systemgli ambiti concedono l'accesso a tutte le risorse FHIR presenti nell' HealthLake archivio dati.

Le sezioni seguenti elencano la sintassi per la costruzione di ambiti di risorse FHIR utilizzando SMART su FHIR V1 o SMART su FHIR V2.

Nota

La strategia di autorizzazione SMART on FHIR viene impostata al momento della creazione dell'archivio dati. Per ulteriori informazioni, consulta AuthorizationStrategy nella documentazione di riferimento dell’API AWS HealthLake .

Ambiti SMART su FHIR V1 supportati da HealthLake

Quando si utilizza SMART su FHIR V1, segue la sintassi generale per la costruzione degli ambiti di risorse FHIR. HealthLake Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante Copia.

('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
SMART on FHIR v1 supportava gli ambiti di autorizzazione
Sintassi dell'ambito Ambito di esempio Risultato

patient/(fhir-resource | '*').('read' | 'write' | '*')

 patient/AllergyIntolerance.* L'applicazione client per i pazienti ha read/write accesso a livello di istanza a tutte le allergie registrate.

user/(fhir-resource | '*').('read' | 'write' | '*')

 user/Observation.read L'applicazione client utente ha accesso a livello di istanza a tutte le osservazioni read/write registrate.
system/('read' | 'write' | *) system/*.* L'applicazione client di sistema ha read/write accesso a tutti i dati delle risorse FHIR.

Ambiti SMART su FHIR V2 supportati da HealthLake

Quando si utilizza SMART su FHIR V2, segue la sintassi generale per la costruzione degli ambiti di risorse FHIR. HealthLake Per visualizzare l'intero percorso dell'URL nell'esempio seguente, scorri il pulsante Copia.

('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
Nota

Per utilizzare SMART su FHIR V2, è necessario inserire il valore permission-v2nella capabilities stringa di metadati, che è un membro del IdentityProviderConfigurationtipo di dati.

HealthLake supporta cannocchiali granulari. Per ulteriori informazioni, consulta gli ambiti granulari supportati nella FHIR US Core Implementation Guide.

Ambiti di autorizzazione supportati da SMART on FHIR V2
Sintassi dell'ambito Esempio di ambito V1 Risultato

patient/Observation.rs

 user/Observation.read Autorizzazione a leggere e cercare Observation risorse per il paziente attuale.

system/*.cruds

 system/*.* L'applicazione client di sistema dispone dell'accesso completo create/read update/delete //search a tutti i dati delle risorse FHIR.

Ambiti SMART su FHIR supportati V2.2 da HealthLake

V2.2 estende gli ambiti V2 con filtri basati sui parametri di ricerca. I server di autorizzazione possono ora emettere ambiti che limitano l'accesso in base a caratteristiche specifiche dei dati e non solo in base al tipo di risorsa e al funzionamento del CRUDS.

Tutto dalla V2 rimane invariato. V2.2 è puramente additivo:

  • Gli ambiti V2 esistenti (senza filtri) continuano a funzionare come prima.

  • La grammatica V2 viene estesa con una stringa di query opzionale. ?param=value

  • Nessuna modifica ai livelli di ambito (patient/user/system), ai tipi di risorse o alle lettere CRUDS.

Prerequisiti

Prima di abilitare SMART su FHIR V2.2, accertatevi di quanto segue:

  • Il tuo data store è stato creato con AuthorizationStrategy set to SMART_ON_FHIR (supporta sia la V1 che la V2). Gli archivi dati che utilizzano SMART_ON_FHIR_V1 o non AWS_AUTH sono idonei.

  • Il tuo archivio dati è già incluso permission-v2 nell'capabilitiesarray. V2.2 è additivo in quanto estende la versione 2 e non può essere utilizzato da solo.

  • Il tuo IDP Lambda è configurato per convalidare e passare attraverso V2.2 il formato scope ? (ambiti contenenti la sintassi delle query).

Abilitazione V2.2

Il percorso di abilitazione dipende dal fatto che si stia creando un nuovo data store o aggiornando uno esistente.

Nuovi archivi dati

Quando crei un nuovo archivio dati, aggiungilo permission-v2.2 all'capabilitiesarray nel Metadata campo del tuo IdentityProviderConfiguration:

"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]
Archivi dati esistenti

Per abilitare SMART su FHIR V2.2 su un data store esistente, aggiungilo permission-v2.2 all'capabilitiesarray nel Metadata campo del tuo IdentityProviderConfiguratione invia la modifica conUpdateFHIRDatastore. Per ulteriori informazioni, consulta Aggiornamento di un archivio HealthLake dati.

Requisiti:

  • permission-v2deve rimanere nell'array. V2.2 estende V2 e non può essere usato da solo.

  • AuthorizationStrategydeve essere SMART_ON_FHIR (non SMART_ON_FHIR_V1 oAWS_AUTH).

  • L'aggiornamento della configurazione del provider di identità la sostituisce completamente, quindi includi tutti i campi e le funzionalità esistenti insieme permission-v2.2 a.

La modifica ha effetto immediato, senza tempi di inattività. Per verificare, recupera Documento Discovery (richiede SigV4):

GET {healthlake-endpoint}/r4/.well-known/smart-configuration

Se l'capabilitiesarray nella risposta includepermission-v2.2, SMART su V2.2 FHIR è attivo.

Sintassi dell'ambito esteso

La grammatica V2 è estesa con una stringa di query opzionale:

V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]
V2.2 scope: componenti della stringa di interrogazione
Componente Description

?param=value

Search-parameter filtro. Sono accessibili solo le risorse che soddisfano questo criterio.

&param=value

Filtro aggiuntivo. Sono disponibili più filtri e D: tutti devono corrispondere.

Regole:

  • I filtri si applicano solo al tipo di risorsa specificato nell'ambito. Wildcard (*) con filtri non è supportata.

  • I parametri devono essere validi per il tipo di risorsa in base alla configurazione di ricerca del data store (check viaGET /r4/metadata).

  • La stringa full scope (ad esempio,patient/Observation.rs?category=laboratory) è il valore letterale visualizzato nel parametro scope OAuth 2.0 e nella dichiarazione del token di accesso. scp

  • URL-encode caratteri speciali per RFC 6749 nelle richieste di autorizzazione (ad esempio, →). | %7C

  • Per i parametri di data, numero e quantità, V2.2 supporta i comparatori di prefissi (ad esempio,). ?date=eq2023-01-01 V2.2 supporta anche i modificatori dei parametri di ricerca.

Esempi di ambito

V2.2 esempi di ambito
Scope Accesso concesso

patient/DiagnosticReport.rs?category=LAB

Solo DiagnosticReport risorse category dov'èLAB.

patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R

Solo Observation risorse con etichetta di sicurezzaRestricted.

patient/Observation.rs?date=ge2023-01-01

Solo Observation risorse datate a partire dal 1° gennaio 2023.

patient/Observation.rs?category=laboratory&status=final

Solo Observation risorse di laboratorio E definitive.

user/Condition.rs?clinical-status=active

Solo Condition risorse attive.

Comportamento di applicazione

Quando un token include V2.2 ambiti, HealthLake applica filtri per operazione:

V2.2 applicazione per operazione
Operation Comportamento

Leggi (r)

Ha successo solo se la risorsa corrisponde a tutti i filtri dell'ambito. Altrimenti restituisce 403.

Cerca () s

I filtri di ambito sono intersecati con la query. Vengono restituite solo le risorse corrispondenti.

Create/Update (c/u)

La risorsa deve soddisfare i filtri di ambito per essere scritta. Altrimenti restituisce 403.

Elimina () d

La risorsa di destinazione deve corrispondere ai filtri dell'ambito. Altrimenti restituisce 403.
Priorità dell'ambito

  • Più V2.2 ambiti per lo stesso tipo di risorsa vengono uniti (OPPURE tra più ambiti).

  • Un ambito V2 più ampio senza filtri (ad esempiopatient/Observation.rs) garantisce l'accesso completo indipendentemente dagli ambiti più ristretti V2.2 dello stesso token.

  • V2.2 gli ambiti su un data store se non sono abilitati vengono ignorati silenziosamente. permission-v2.2

Limitazioni

Quanto segue non è supportato nei V2.2 filtri di ambito:

  • Parametri di ricerca compositi (ad esempio,code-value-quantity).

  • Parametri di ricerca concatenati (ad esempio,subject:Patient.name=Smith).

  • _include/parametri _revinclude di ricerca.

  • $export/$davinci-data-export(Bulk Data): i V2.2 filtri non si applicano; l'esportazione in blocco utilizza ambiti V2.

  • Tipo di risorsa Wildcard combinato con filtri (ad esempio, non valido). patient/*.rs?category=LAB È necessario specificare un tipo di risorsa esplicito quando si utilizzano i filtri dei parametri di ricerca (ad esempio,). patient/Observation.rs?category=LAB

Risoluzione dei problemi
Caratteristiche Causa Correggere

Ambito del token non riconosciuto

V2.2 non abilitato nell'archivio dati

Verifica /.well-known/smart-configuration e richiedi l'abilitazione tramite un ticket di supporto.

403 su una risorsa esistente

La risorsa non corrisponde al filtro dell'ambito

Verifica i valori delle risorse rispetto ai parametri dell'ambito.

Risultati di ricerca vuoti

Filtro di ambito più ristretto della query

I risultati sono l'intersezione dei filtri di interrogazione e di ambito.

Errore InvalidScope

Parametro di ricerca non valido nell'ambito

Conferma il parametro tramite /metadata CapabilityStatement.

End-to-end esempio

Scenario: un'app per pazienti dovrebbe mostrare solo i risultati di laboratorio definitivi a partire dal 2023.

  1. Il server di autorizzazione emette un token con ambito:

    patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01

  2. Chiamate client HealthLake:

    GET {endpoint}/r4/Observation?patient=Patient/123

  3. HealthLake applica i filtri di ambito. La risposta contiene solo Observation risorse in cui category=laboratory AND AND status=final ANDdate ≥ 2023-01-01, anche se il client ha richiesto tutte le osservazioni.