As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # SMART em escopos FHIR OAuth 2.0 suportados por HealthLake HealthLake usa o OAuth 2.0 como protocolo de autorização. O uso desse protocolo em seu servidor de autorização permite definir permissões de armazenamento de HealthLake dados (criar, ler, atualizar, excluir e pesquisar) para recursos FHIR aos quais um aplicativo cliente tem acesso. A estrutura SMART on FHIR define um conjunto de escopos que podem ser solicitados do servidor de autorização. Por exemplo, um aplicativo cliente projetado apenas para permitir que os pacientes visualizem seus resultados laboratoriais ou visualizem seus detalhes de contato só deve ser *autorizado* a solicitar `read` escopos. **nota** HealthLake fornece suporte para SMART no FHIR V1 e V2, conforme descrito abaixo. O SMART no 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)é definido para um dos três valores a seguir quando seu armazenamento de dados é criado: `SMART_ON_FHIR_V1`— Support somente para SMART no FHIR V1, que inclui permissões `read` (read/search) e `write` (create/update/delete). `SMART_ON_FHIR`— Support para SMART no FHIR V1 e V2, que inclui,`create`, `read``update`, `delete` e permissões. `search` `AWS_AUTH`— A estratégia de AWS HealthLake autorização padrão; não afiliada à SMART no FHIR. ## Escopo de lançamento independente HealthLake suporta o escopo `launch/patient` do modo de inicialização autônomo. No modo de inicialização autônomo, um aplicativo cliente solicita acesso aos dados clínicos do paciente porque o usuário e o paciente não são conhecidos pelo aplicativo cliente. Assim, a solicitação de autorização do aplicativo do cliente solicita explicitamente que o escopo do paciente seja devolvido. Após a autenticação bem-sucedida, o servidor de autorização emite um token de acesso contendo o escopo do paciente de lançamento solicitado. O contexto necessário do paciente é fornecido junto com o token de acesso na resposta do servidor de autorização. **Escopos do modo de lançamento suportados** | Escopo | Description | | --- | --- | | `launch/patient` | Um parâmetro em uma solicitação de autorização do OAuth 2.0 solicitando que os dados do paciente sejam retornados na resposta de autorização. | ## SMART nos escopos de recursos do FHIR para HealthLake HealthLake define três níveis de SMART nos escopos de recursos do FHIR. + `patient`os escopos concedem acesso a dados específicos sobre um único paciente. + `user`os escopos concedem acesso a dados específicos que um usuário pode acessar. + `system`os escopos concedem acesso a todos os recursos do FHIR encontrados no armazenamento de dados. HealthLake As seções a seguir listam a sintaxe para construir escopos de recursos FHIR usando SMART no FHIR V1 ou SMART no FHIR V2. **nota** A estratégia de autorização SMART on FHIR é definida quando seu armazenamento de dados é criado. Para obter mais informações, consulte [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) na *Referência de APIs do AWS HealthLake *. ### SMART em escopos FHIR V1 suportados por HealthLake Ao usar o SMART no FHIR V1, a sintaxe geral para construir escopos de recursos do FHIR é a seguinte. HealthLake Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**. ``` ('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*') ``` **SMART em escopos de autorização compatíveis com FHIR v1** | Sintaxe do escopo | Exemplo de escopo | Resultado | | --- | --- | --- | | `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\* | O aplicativo cliente do paciente tem read/write acesso em nível de instância a todas as alergias registradas. | | `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | O aplicativo cliente do usuário tem read/write acesso em nível de instância a todas as observações registradas. | | system/('read' \| 'write' \| \*) | system/\*.\* | O aplicativo cliente do sistema tem read/write acesso a todos os dados de recursos do FHIR. | ### SMART em escopos FHIR V2 suportados por HealthLake Ao usar o SMART no FHIR V2, a sintaxe geral para construir escopos de recursos do FHIR é a seguinte. HealthLake Para ver todo o caminho do URL no exemplo a seguir, role até o botão **Copiar**. ``` ('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's') ``` **nota** Para usar o SMART no FHIR V2, você deve passar o valor [https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)para a `capabilities` string de metadados, que é um membro do tipo de dados. [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) HealthLake suporta escopos granulares. Para obter mais informações, consulte os [escopos granulares compatíveis](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported) no *FHIR US* Core Implementation Guide. **SMART em escopos de autorização compatíveis com FHIR V2** | Sintaxe do escopo | Exemplo de escopo V1 | Resultado | | --- | --- | --- | | `patient/Observation.rs` | user/Observation.read | Permissão para ler e pesquisar Observation recursos para o paciente atual. | | `system/*.cruds` | system/\*.\* | O aplicativo cliente do sistema tem acesso completo create/read update/delete //search a todos os dados de recursos do FHIR. | ### SMART em V2.2 escopos FHIR suportados por HealthLake V2.2 estende os escopos da V2 com filtragem baseada em parâmetros de pesquisa. Agora, os servidores de autorização podem emitir escopos que restringem o acesso por características de dados específicas e não apenas por tipo de recurso e operação CRUDS. Tudo da V2 permanece inalterado. V2.2 é puramente aditivo: + Os escopos V2 existentes (sem filtros) continuam funcionando como antes. + A gramática V2 é estendida com uma string de `?param=value` consulta opcional. + Nenhuma alteração nos níveis de escopo (`patient`/`user`/`system`), nos tipos de recursos ou nas letras CRUDS. #### Pré-requisitos Antes de ativar o SMART no FHIR V2.2, verifique o seguinte: + Seu armazenamento de dados foi criado com `AuthorizationStrategy` set to `SMART_ON_FHIR` (suporta V1 e V2). Armazenamentos de dados que usam `SMART_ON_FHIR_V1` ou não `AWS_AUTH` são elegíveis. + Seu armazenamento de dados já está incluído `permission-v2` na `capabilities` matriz. V2.2 é aditivo, pois estende a V2 e não pode ser usado de forma independente. + Seu IDP Lambda está configurado para validar e passar pelo formato V2.2 do escopo (escopos `?` contendo sintaxe de consulta). #### Habilitando V2.2 O caminho de habilitação depende se você está criando um novo armazenamento de dados ou atualizando um existente. ##### Novos armazenamentos de dados Ao criar um novo armazenamento de dados, adicione `permission-v2.2` à `capabilities` matriz no `Metadata` campo do seu [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" ] ``` ##### Armazenamentos de dados existentes Para habilitar o SMART V2.2 no FHIR em um armazenamento de dados existente, adicione `permission-v2.2` à `capabilities` matriz no `Metadata` campo seu [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)e envie a alteração com. `UpdateFHIRDatastore` Para obter mais informações, consulte [Atualizando um armazenamento HealthLake de dados](managing-data-stores-update.md). Requisitos: + `permission-v2`deve permanecer na matriz. V2.2 estende a V2 e não pode ser usado sozinho. + `AuthorizationStrategy`deve ser `SMART_ON_FHIR` (não `SMART_ON_FHIR_V1` ou`AWS_AUTH`). + A atualização da configuração do provedor de identidade a substitui totalmente, portanto, inclua todos os campos e recursos existentes. `permission-v2.2` A alteração entra em vigor imediatamente, sem tempo de inatividade. Para verificar, busque o [Documento de descoberta](reference-smart-on-fhir-discovery-document.md) (requer SigV4): ``` GET {healthlake-endpoint}/r4/.well-known/smart-configuration ``` Se a `capabilities` matriz na resposta incluir`permission-v2.2`, o SMART no FHIR estará V2.2 ativo. #### Sintaxe de escopo estendido A gramática V2 é estendida com uma string de consulta opcional: ``` V2: (patient|user|system) / resource . cruds V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]] ``` **V2.2 componentes da string de consulta de escopo** | Componente | Description | | --- | --- | | `?param=value` | Search-parameter filtrar. Somente os recursos que correspondem a esse critério estão acessíveis. | | `¶m=value` | Filtro adicional. Vários filtros são e Ed — todos devem corresponder. | Regras: + Os filtros se aplicam somente ao tipo de recurso especificado no escopo. Não há suporte para Wildcard (`*`) com filtros. + Os parâmetros devem ser válidos para o tipo de recurso de acordo com a configuração de pesquisa do seu armazenamento de dados (verifique via`GET /r4/metadata`). + A string de escopo completo (por exemplo,`patient/Observation.rs?category=laboratory`) é o valor literal que aparece no parâmetro de escopo do OAuth 2.0 e na declaração do token de acesso. `scp` + URL-encode caracteres especiais de acordo com [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) em solicitações de autorização (por exemplo, `|` →`%7C`). + Para parâmetros de data, número e quantidade, V2.2 suporta [comparadores](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators) de prefixo (por exemplo,`?date=eq2023-01-01`). V2.2 também suporta [modificadores de parâmetros de pesquisa](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers). #### Exemplos de escopo **V2.2 exemplos de escopo** | Escopo | Acesso concedido | | --- | --- | | `patient/DiagnosticReport.rs?category=LAB` | Somente `DiagnosticReport` recursos onde `category` estão`LAB`. | | `patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R` | Somente `Observation` recursos com etiqueta de segurança`Restricted`. | | `patient/Observation.rs?date=ge2023-01-01` | Somente `Observation` recursos datados em ou após 1º de janeiro de 2023. | | `patient/Observation.rs?category=laboratory&status=final` | Somente `Observation` recursos que são laboratoriais e finais. | | `user/Condition.rs?clinical-status=active` | Somente `Condition` recursos ativos. | #### Comportamento de aplicação Quando um token inclui V2.2 escopos, HealthLake aplica filtros por operação: **V2.2 fiscalização por operação** | Operation | Comportamento | | --- | --- | | Leia (`r`) | Só será bem-sucedido se o recurso corresponder a todos os filtros de escopo. Caso contrário, retorna 403. | | Pesquisar (`s`) | Os filtros de escopo são cruzados com a consulta. Somente os recursos correspondentes são retornados. | | Create/Update (`c`/`u`) | O recurso deve satisfazer os filtros de escopo para ser escrito. Caso contrário, retorna 403. | | Excluir (`d`) | O recurso de destino deve corresponder aos filtros de escopo. Caso contrário, retorna 403. | ##### Precedência do escopo + Vários V2.2 escopos para o mesmo tipo de recurso são unidos (OU entre escopos). + Um escopo V2 mais amplo sem filtros (por exemplo,`patient/Observation.rs`) concede acesso total, independentemente de qualquer V2.2 escopo mais estreito no mesmo token. + V2.2 os escopos em um armazenamento de dados sem `permission-v2.2` habilitado são ignorados silenciosamente. #### Limitações Os itens a seguir não são compatíveis com filtros de V2.2 escopo: + Parâmetros de pesquisa compostos (por exemplo,`code-value-quantity`). + Parâmetros de pesquisa encadeados (por exemplo,`subject:Patient.name=Smith`). + `_include`/parâmetros `_revinclude` de pesquisa. + `$export`/`$davinci-data-export`(Dados em massa) — V2.2 os filtros não se aplicam; a exportação em massa usa escopos V2. + Tipo de recurso curinga combinado com filtros (por exemplo, `patient/*.rs?category=LAB` é inválido). Você deve especificar um tipo de recurso explícito ao usar filtros de parâmetros de pesquisa (por exemplo,). `patient/Observation.rs?category=LAB` **Solução de problemas** | Sintomas | Causa | Correção | | --- | --- | --- | | Escopo do token não reconhecido | V2.2 não habilitado no armazenamento de dados | Verifique `/.well-known/smart-configuration` e solicite a capacitação por meio de um ticket de suporte. | | 403 em um recurso que existe | O recurso não corresponde ao filtro de escopo | Verifique os valores dos recursos em relação aos parâmetros do escopo. | | Resultados de pesquisa vazios | Filtro de escopo mais estreito que a consulta | Os resultados são a interseção dos filtros de consulta e escopo. | | Erro `InvalidScope` | Parâmetro de pesquisa inválido no escopo | Confirme o parâmetro via `/metadata` CapabilityStatement. | #### End-to-end exemplo Cenário: um aplicativo para pacientes só deve mostrar os resultados laboratoriais finalizados a partir de 2023. 1. O servidor de autorização emite um token com o escopo: ``` patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01 ``` 1. Chamadas do cliente HealthLake: ``` GET {endpoint}/r4/Observation?patient=Patient/123 ``` 1. HealthLake impõe filtros de escopo. A resposta contém somente `Observation` recursos onde `category=laboratory` AND `status=final` AND `date ≥ 2023-01-01` — mesmo que o cliente tenha solicitado todas as observações.