Escopo de lançamento independente SMART nos escopos de recursos do FHIR para HealthLake

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 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, readupdate, 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.

patientos escopos concedem acesso a dados específicos sobre um único paciente.
useros escopos concedem acesso a dados específicos que um usuário pode acessar.
systemos 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 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 permission-v2para a capabilities string de metadados, que é um membro do tipo de dados. IdentityProviderConfiguration

HealthLake suporta escopos granulares. Para obter mais informações, consulte os escopos granulares compatíveis 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 IdentityProviderConfiguration:


"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 IdentityProviderConfiguratione envie a alteração com. UpdateFHIRDatastore Para obter mais informações, consulte Atualizando um armazenamento HealthLake de dados.

Requisitos:

permission-v2deve permanecer na matriz. V2.2 estende a V2 e não pode ser usado sozinho.
AuthorizationStrategydeve ser SMART_ON_FHIR (não SMART_ON_FHIR_V1 ouAWS_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 (requer SigV4):


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

Se a capabilities matriz na resposta incluirpermission-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.
`&param=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 viaGET /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 em solicitações de autorização (por exemplo, | →%7C).
Para parâmetros de data, número e quantidade, V2.2 suporta comparadores de prefixo (por exemplo,?date=eq2023-01-01). V2.2 também suporta modificadores de parâmetros de pesquisa.

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.

O servidor de autorização emite um token com o escopo:


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

Chamadas do cliente HealthLake:


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

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.

Convenções do documento

Autenticação

Validação de token