Conectar-se a aplicativos usando SMART no FHIR

Nesta página, descrevemos como usar o SMART (Aplicativo Médico Substitutável, Tecnologias Reutilizáveis) SMART no FHIR v1.1.0 (link em inglês) para acessar dados em armazenamentos FHIR na API Cloud Healthcare.

Visão geral

O SMART no FHIR é um padrão de dados que permite que os aplicativos acessem informações em sistemas de registros eletrônicos de saúde (EHR, na sigla em inglês). Um desenvolvedor de aplicativos pode gravar um único aplicativo que se conecta a qualquer sistema de EHR que tenha adotado o padrão.

Por exemplo, se você tiver dados de pacientes armazenados em um armazenamento FHIR na API Cloud Healthcare, será possível desenvolver um aplicativo que faça o seguinte:

  1. Autentica ao armazenamento de FHIR.
  2. Recupera os dados do paciente.
  3. Exibe os dados do paciente em uma interface do usuário.

O SMART no FHIR é compatível com os modelos de autorização OpenID e OAuth 2.0 para autorização e autenticação.

Estrutura, escopos e contexto do lançamento de aplicativos SMART

A API Cloud Healthcare oferece suporte ao framework de lançamento de apps SMART, escopos e contexto de inicialização da seguinte maneira:

Framework de inicialização do aplicativo SMART

A API Cloud Healthcare oferece suporte à sequência de lançamento independente do Framework de inicialização do aplicativo SMART.

Um app pode ser iniciado em um sistema de EHR ou em uma sessão do portal do paciente, ambos chamados de "lançamento de EHR" ou como um app independente.

Escopos

Os escopos de dados clínicos definem permissões de leitura e gravação para acesso específico para pacientes e usuários. A API Cloud Healthcare oferece suporte aos seguintes escopos de dados definidos em Escopos para solicitar dados clínicos:

  • patient
  • user
  • system
Contexto do lançamento

Descreve o paciente atual, o encontro ou outro contexto em que a solicitação está sendo feita. A API Cloud Healthcare oferece suporte ao contexto de lançamento do paciente em Escopos para solicitar dados de contexto.

Configurar seu servidor de autorização para SMART no FHIR

A API Cloud Healthcare fornece suporte integrado para aplicação de acesso a SMART no FHIR com base nos escopos de autorização SMART de entrada e no contexto do paciente. Os administradores de armazenamento FHIR criam e configuram um servidor de autorização fora da API Cloud Healthcare que concede escopos de autorização SMART e contexto do paciente.

Se um aplicativo cliente receber um token de acesso que representa os escopos de autorização SMART concedidos e o contexto do paciente, a API Cloud Healthcare não especificará qual fluxo de trabalho de inicialização o aplicativo cliente precisa usar com o servidor de autorização externo.

Definir e validar escopos de autorização SMART

Se você estiver usando o SMARTProxy, pule esta seção. O SMARTProxy define e valida escopos de autorização SMART automaticamente.

Os escopos de autorização SMART usam o seguinte formato:

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

Os escopos de autorização SMART e os contextos dos pacientes são transmitidos para a API Cloud Healthcare usando os cabeçalhos HTTP X-Authorization-. A API Cloud Healthcare usa esses cabeçalhos para impor o controle de acesso a dados em armazenamentos FHIR.

O servidor de autorização concede os escopos de autorização SMART e o contexto do paciente e os codifica em um token de acesso. Em seguida, o proxy lê as informações no token de acesso e as transmite para os cabeçalhos da solicitação FHIR.

Se você não tiver um servidor de autorização, use o acelerador de interoperabilidade baseado na Apigee HealthAPIx na Apigee.

Use o SMART a seguir em cabeçalhos HTTP FHIR ao fazer solicitações do proxy. O aplicativo cliente não precisa definir esses cabeçalhos porque eles só são transmitidos do proxy para a API Cloud Healthcare.

  • X-Authorization-Scope: um ou mais escopos de autorização que usam os formatos padrão de escopo de autorização SMART. Por exemplo, definir o escopo de autorização como user/Observation.read significa que uma solicitação só pode ler um recurso Observação. A API Cloud Healthcare aplica esse controle de acesso.
  • X-Authorization-Patient: o contexto do paciente da solicitação. Quando você define esse cabeçalho, todos os tipos de recursos na solicitação qualificados para estar em um compartimento de paciente precisam pertencer ao compartimento de paciente do ID de paciente informado. Essa API aplica esse controle de acesso.
  • X-Authorization-Subject: um identificador para o usuário final que acessa o SMART no aplicativo cliente FHIR. A API Cloud Healthcare registra o assunto em Registros de auditoria.
  • X-Authorization-Issuer: o emissor do token de acesso SMART. A API Cloud Healthcare registra o emissor em Registros de auditoria.

Configurar os tokens de acesso do servidor de autorização

Para emitir um token JWT, configure um servidor de autorização. O token JWT contém os escopos de autorização do SMART e, opcionalmente, o contexto do paciente. A API Cloud Healthcare não tem requisitos específicos sobre como o servidor de autorização gera o token SMART JWT. Por exemplo, seu aplicativo pode estar registrado em um subconjunto de escopos ou apresentar um widget de seleção de paciente para definir o contexto do paciente.

Se você não tiver um servidor de autorização que configure tokens JWT SMART, use o acelerador de interoperabilidade baseado na Apigee HealthAPIx na Apigee (links em inglês) para configurar um servidor de autenticação que assina tokens JWT.

Exemplo de token de acesso

Veja na amostra a seguir um token de acesso codificado em base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Depois de decodificar o token de acesso, ele contém o seguinte payload:

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

Configurar SMART no FHIR na API Cloud Healthcare

Esta seção descreve as etapas que você precisa seguir para começar a usar o SMART no FHIR com dados na API Cloud Healthcare.

Configurar o SMARTProxy

Se você estiver usando seu próprio servidor de autorização em vez do SMARTProxy, pule esta seção e continue para Configurar uma conta de serviço do Google Cloud.

O SMARTProxy é um proxy de código aberto do Google que fornece os seguintes recursos:

  • Permite que a API Cloud Healthcare aceite e valide tokens de acesso SMART.
  • Permite que a implementação FHIR na API Cloud Healthcare inclua tokens de acesso SMART como parte do modelo de gerenciamento e permissão da API.

Quando você faz uma solicitação para recuperar dados da API Cloud Healthcare pelo SMARTProxy, a solicitação segue estas etapas:

  1. O SMARTProxy aceita uma solicitação que contém um token SMART de um cliente.
  2. O SMARTProxy valida o token SMART por meio do servidor de autorização JWT.
  3. O SMARTProxy lê os escopos e o contexto do paciente do token SMART e os transmite para a API Cloud Healthcare usando quatro cabeçalhos HTTP.
  4. A API Cloud Healthcare recebe os cabeçalhos e os valida para aplicar o controle de acesso à solicitação. Em seguida, a API Cloud Healthcare retorna uma resposta ao cliente por meio do SMARTProxy.

Configurar uma conta de serviço do Google Cloud

Um proxy só pode ter uma conta de serviço do Google Cloud. Se vários clientes usarem o mesmo proxy, todos precisarão utilizar a mesma conta de serviço. Tenha cuidado ao compartilhar uma conta de serviço com vários clientes pelos seguintes motivos:

  • Para ler os dados FHIR na API Cloud Healthcare, a conta de serviço tem permissões amplas de leitura e gravação.

  • O endereço de e-mail principal dos registros de auditoria do Cloud está vinculado à conta de serviço.

    Por exemplo, se você chamar a API Cloud Healthcare usando sua Conta do Google para autenticação, os Registros de auditoria do Cloud registrarão seu endereço de e-mail como o endereço de e-mail principal. Quando você usa um proxy para chamar a API Cloud Healthcare, o proxy usa a própria conta de serviço, e o endereço de e-mail da conta de serviço é o endereço de e-mail principal. Portanto, o autor da chamada original fica oculto. Para salvar o usuário final nos metadados do registro de auditoria, transmita o endereço de e-mail do usuário final no campo sub do token JWT.

Configurar um armazenamento FHIR

Não é preciso configurar o armazenamento FHIR que contém os dados FHIR que você está acessando.

Fazer SMART em solicitações FHIR

Esta seção fornece uma visão geral dos métodos SMART compatíveis com FHIR na API Cloud Healthcare e como o acesso a recursos é aplicado quando você faz uma solicitação SMART no FHIR.

Ao fazer uma solicitação, seu servidor de autorização é responsável por gerar tokens de acesso com o escopo de autorização SMART relevante e o contexto de inicialização.

Métodos aceitos

A API Cloud Healthcare oferece suporte ao SMART no FHIR de todos os métodos projects.locations.datasets.fhirStores.fhir, exceto:

Aplicação de acesso a recursos

Ao fazer uma solicitação SMART no FHIR para um armazenamento de FHIR, o controle de acesso ocorre na seguinte ordem:

  1. A API Cloud Healthcare verifica as permissões na conta de serviço do Google Cloud configurada no proxy. Se a conta de serviço tiver as permissões corretas do IAM no armazenamento FHIR, a solicitação vai prosseguir.
  2. A API Cloud Healthcare verifica se o token SMART tem as permissões apropriadas para acessar cada recurso FHIR solicitado pela solicitação.

O compartimento de pacientes é fundamental para a lógica de aplicação de acesso na API Cloud Healthcare. O SMART no FHIR tem uma lista de tipos de recursos FHIR qualificados para serem incluídos em um compartimento do paciente. Os tipos de recursos também têm os próprios critérios de inclusão. No restante desta seção, os tipos de recursos qualificados são chamados de "tipos de recursos qualificados para compartimentos de pacientes". Os tipos de recursos não qualificados são chamados de "tipos de recursos não qualificados no compartimento de pacientes".

O SMART em solicitações FHIR para um armazenamento FHIR precisa atender aos seguintes requisitos:

  • Forneça o papel patient, user ou system nos escopos de autorização SMART. Se você atribuir o papel patient, especifique o contexto do paciente. O contexto do paciente é o ID lógico do recurso do paciente. O recurso "paciente" já precisa existir no armazenamento FHIR ou existir após a solicitação ser feita. Caso contrário, a API Cloud Healthcare a rejeitará.

  • Ao criar, ler, atualizar ou excluir um recurso, o resourceType e o tipo de operação (read ou write) precisam ser correspondentes. Caso contrário, a API Cloud Healthcare rejeitará a solicitação.

  • Se você fornecer um escopo patient contendo tipos de recurso não qualificados no compartimento do paciente, como patient/Practitioner.*, a verificação de validação do escopo vai falhar, e a API Cloud Healthcare vai rejeitar o escopo.

  • É possível definir todos os tipos de recursos com o escopo user. Se um contexto de paciente estiver presente com um escopo user, os tipos de recursos qualificados para o compartimento do paciente serão restritos ao contexto do paciente. Os tipos de recurso restantes ignoram o contexto do paciente.

  • A presença de um contexto do paciente restringe os tipos de recursos qualificados do compartimento do paciente a ele. Por exemplo, um recurso de observação precisa fazer com que o campo subject referencie o recurso "Paciente" fornecido para que a observação seja acessível. Consulte os tipos de acesso ao compartimento de pacientes em Resource CompartmentDefinition - Content para ver uma lista de quais campos em cada tipo de recurso do compartimento de pacientes precisam ser referenciados ao paciente para que o recurso seja considerado dentro do compartimento de pacientes.

  • As solicitações podem conter os escopos patient e user.

  • Não use o escopo system com o contexto do paciente. Caso contrário, a solicitação falhará.

  • Não use o escopo system com o escopo patient ou user.

  • Se você chamar um método que acesse vários recursos (por exemplo, os métodos fhir.Patient-everything, fhir.executeBundle ou fhir.search), o controle de acesso se aplica a cada recurso individual.