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 [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-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` `update``delete`, 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. + `patient`gli ambiti garantiscono l'accesso a dati specifici su un singolo paziente. + `user`gli ambiti garantiscono l'accesso a dati specifici a cui un utente può accedere. + `system`gli 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 [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-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 [https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)nella `capabilities` stringa di metadati, che è un membro del [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)tipo di dati. HealthLake supporta cannocchiali granulari. Per ulteriori informazioni, consulta gli [ambiti granulari supportati](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported) 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'`capabilities`array. 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'`capabilities`array nel `Metadata` campo del tuo [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html): ``` "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'`capabilities`array nel `Metadata` campo del tuo [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)e invia la modifica con`UpdateFHIRDatastore`. Per ulteriori informazioni, consulta [Aggiornamento di un archivio HealthLake dati](managing-data-stores-update.md). Requisiti: + `permission-v2`deve rimanere nell'array. V2.2 estende V2 e non può essere usato da solo. + `AuthorizationStrategy`deve essere `SMART_ON_FHIR` (non `SMART_ON_FHIR_V1` o`AWS_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](reference-smart-on-fhir-discovery-document.md) (richiede SigV4): ``` GET {healthlake-endpoint}/r4/.well-known/smart-configuration ``` Se l'`capabilities`array nella risposta include`permission-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. | | `¶m=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 via`GET /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](https://datatracker.ietf.org/doc/html/rfc6749) nelle richieste di autorizzazione (ad esempio, →). `|` `%7C` + Per i parametri di data, numero e quantità, V2.2 supporta i [comparatori](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators) di prefissi (ad esempio,). `?date=eq2023-01-01` V2.2 supporta anche i modificatori [dei parametri di ricerca](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers). #### 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 sicurezza`Restricted`. | | `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 esempio`patient/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 ``` 1. Chiamate client HealthLake: ``` GET {endpoint}/r4/Observation?patient=Patient/123 ``` 1. HealthLake applica i filtri di ambito. La risposta contiene solo `Observation` risorse in cui `category=laboratory` AND AND `status=final` AND`date ≥ 2023-01-01`, anche se il client ha richiesto tutte le osservazioni.