Estabeleça ligação a aplicações através do SMART on FHIR

Esta página descreve como usar a norma SMART (Substitutable Medical Applications, Reusable Technologies) on FHIR v1.1.0 para aceder aos dados em arquivos FHIR na Cloud Healthcare API.

Vista geral

O SMART on FHIR é uma norma de dados que permite que as aplicações acedam a informações em sistemas de registos de saúde eletrónicos (RSE). Um programador de aplicações pode escrever uma única aplicação que se ligue a qualquer sistema de RSE que tenha adotado a norma.

Por exemplo, se tiver dados de pacientes armazenados num FHIR store na Cloud Healthcare API, pode desenvolver uma aplicação que faça o seguinte:

  1. Autentica-se na loja FHIR.
  2. Obtém os dados do paciente.
  3. Apresenta os dados do paciente numa interface do utilizador.

A SMART on FHIR suporta os modelos de autorização OpenID e OAuth 2.0 para autorização e autenticação.

Framework SMART App Launch, âmbitos e contexto de lançamento

A Cloud Healthcare API suporta a Framework SMART App Launch, os âmbitos e o contexto de lançamento da seguinte forma:

Estrutura de lançamento de apps SMART

A Cloud Healthcare API suporta a sequência de lançamento autónomo da SMART App Launch Framework.

Uma app pode ser iniciada a partir de uma sessão existente do sistema RSE ou do portal de pacientes, ambos denominados "início do RSE", ou como uma app autónoma.

Âmbitos

Os âmbitos de dados clínicos definem as autorizações de leitura e escrita para o acesso específico do paciente e ao nível do utilizador. A Cloud Healthcare API suporta os seguintes âmbitos de dados definidos em Âmbitos para pedir dados clínicos:

  • patient
  • user
  • system
Contexto de lançamento

Descreve o paciente, o encontro ou outro contexto atual em que o pedido está a ser feito. A Cloud Healthcare API suporta o contexto de lançamento do paciente a partir de âmbitos para pedir dados de contexto.

Configure o seu servidor de autorização para SMART on FHIR

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

Se uma aplicação cliente obtiver um token de acesso que represente os âmbitos de autorização SMART concedidos e o contexto do paciente, a Cloud Healthcare API não especifica o fluxo de trabalho de lançamento que a aplicação cliente tem de usar com o servidor de autorização externo.

Defina e valide os âmbitos de autorização SMART

Se estiver a usar o SMARTProxy, pode ignorar esta secção. O SMARTProxy define e valida automaticamente os âmbitos de autorização SMART.

Os âmbitos de autorização SMART usam o seguinte formato:

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

Os âmbitos de autorização SMART e os contextos dos pacientes são transmitidos à Cloud Healthcare API através de cabeçalhos HTTP X-Authorization-. A Cloud Healthcare API usa estes cabeçalhos para aplicar o controlo de acesso aos dados em arquivos FHIR.

O seu servidor de autorização concede os âmbitos de autorização SMART e o contexto do paciente e codifica-os num token de acesso. Em seguida, o proxy lê as informações no token de acesso e transmite-as para os cabeçalhos de pedidos FHIR.

Se não tiver um servidor de autorização, pode usar o acelerador de interoperabilidade baseado no Apigee HealthAPIx no Apigee.

Use os seguintes cabeçalhos HTTP SMART on FHIR quando fizer pedidos a partir do proxy. A aplicação cliente não precisa de definir estes cabeçalhos porque só são transmitidos do proxy para a API Cloud Healthcare.

  • X-Authorization-Scope: um ou mais âmbitos de autorização que usam os formatos de âmbito de autorização SMART padrão. Por exemplo, definir o âmbito de autorização como user/Observation.read significa que um pedido só pode ler um recurso de observação. A Cloud Healthcare API aplica este controlo de acesso.
  • X-Authorization-Patient: o contexto do paciente do pedido. Quando define este cabeçalho, todos os tipos de recursos no pedido que sejam elegíveis para estar num compartimento do paciente têm de pertencer ao compartimento do paciente do ID do paciente fornecido. A API Cloud Healthcare aplica este controlo de acesso.
  • X-Authorization-Subject: um identificador do utilizador final que acede à aplicação cliente SMART on FHIR. A Cloud Healthcare API regista o assunto nos registos de auditoria.
  • X-Authorization-Issuer: o emissor do token de acesso SMART. A API Cloud Healthcare regista o emissor nos registos de auditoria.

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

Para emitir um token JWT, tem de configurar um servidor de autorização. O token JWT contém os âmbitos de autorização SMART e, opcionalmente, o contexto do paciente. A Cloud Healthcare API não tem requisitos específicos sobre a forma como o servidor de autorização gera o token JWT SMART. Por exemplo, a sua aplicação pode estar registada para um subconjunto de âmbitos ou apresentar um widget de seleção de pacientes para definir o contexto do paciente.

Se não tiver um servidor de autorização que configure tokens JWT SMART, pode usar o acelerador de interoperabilidade baseado no Apigee HealthAPIx no Apigee para configurar um servidor de autenticação que assine tokens JWT.

Exemplo de chave de acesso

O exemplo seguinte mostra um token de acesso codificado em base64:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

Depois de descodificar o token de acesso, este contém a seguinte carga útil:

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

Configure a SMART on FHIR na Cloud Healthcare API

Esta secção descreve os passos que tem de seguir para começar a usar o SMART on FHIR com dados na Cloud Healthcare API.

Configure o SMARTProxy

Se estiver a usar o seu próprio servidor de autorização em vez do SMARTProxy, ignore esta secção e continue para Configurar uma Google Cloud conta de serviço.

O SMARTProxy é um proxy de código aberto da Google que oferece as seguintes funcionalidades:

  • Permite que a Cloud Healthcare API aceite e valide tokens de acesso SMART.
  • Permite que a implementação da FHIR na Cloud Healthcare API inclua tokens de acesso SMART como parte da gestão de APIs e do modelo de autorizações.

Quando faz um pedido para obter dados da Cloud Healthcare API através do SMARTProxy, o pedido segue estes passos:

  1. O SMARTProxy aceita um pedido que contenha um token SMART de um cliente.
  2. O SMARTProxy valida o token SMART através do seu servidor de autorização JWT.
  3. O SMARTProxy lê os âmbitos e o contexto do paciente a partir do token SMART e transmite-os à Cloud Healthcare API através de quatro cabeçalhos HTTP.
  4. A Cloud Healthcare API recebe os cabeçalhos e valida-os para aplicar o controlo de acesso ao pedido. Em seguida, a Cloud Healthcare API devolve uma resposta através do SMARTProxy ao cliente.

Configure uma Google Cloud conta de serviço

Um proxy só pode ter uma Google Cloud conta de serviço. Se vários clientes usarem o mesmo proxy, têm de usar a mesma conta de serviço. Tenha cuidado ao partilhar uma conta de serviço com vários clientes pelos seguintes motivos:

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

  • O endereço de email principal dos registos de auditoria do Cloud está associado à conta de serviço.

    Por exemplo, se chamar a Cloud Healthcare API através da sua Conta Google para autenticação, os registos do Cloud Audit Logs registam o seu endereço de email como o endereço de email principal. Quando usa um proxy para chamar a Cloud Healthcare API, o proxy usa a sua própria conta de serviço e o endereço de email da conta de serviço é o endereço de email principal, pelo que o autor da chamada original fica oculto. Para guardar o utilizador final nos metadados do registo de auditoria, transmita o endereço de email do utilizador final no campo sub do token JWT.

Configure uma loja FHIR

Não tem de configurar o arquivo FHIR que contém os dados FHIR aos quais está a aceder.

Faça pedidos SMART on FHIR

Esta secção oferece uma vista geral dos métodos SMART on FHIR suportados na API Cloud Healthcare e como o acesso aos recursos é aplicado quando faz um pedido SMART on FHIR.

Ao fazer um pedido, o seu servidor de autorização é responsável por gerar tokens de acesso com o âmbito de autorização SMART relevante e o contexto de lançamento.

Métodos suportados

A Cloud Healthcare API suporta SMART on FHIR para todos os métodos projects.locations.datasets.fhirStores.fhir, exceto os seguintes:

Aplicação do acesso a recursos

Quando faz um pedido SMART on FHIR a uma FHIR store, o controlo de acesso ocorre pela seguinte ordem:

  1. A Cloud Healthcare API verifica as autorizações na Google Cloud conta de serviço configurada no proxy. Se a conta de serviço tiver as autorizações de IAM corretas na loja FHIR, o pedido prossegue.
  2. A Cloud Healthcare API verifica se o token SMART tem as autorizações adequadas para aceder a cada recurso FHIR solicitado.

O compartimento do paciente é fundamental para a lógica de aplicação do acesso na Cloud Healthcare API. O SMART on FHIR tem uma lista de tipos de recursos do FHIR elegíveis para inclusão num compartimento do paciente. Os tipos de recursos também têm os seus próprios critérios de inclusão. No resto desta secção, os tipos de recursos elegíveis são denominados "tipos de recursos elegíveis para o compartimento do paciente". Os tipos de recursos não elegíveis são denominados "tipos de recursos não elegíveis para o compartimento de pacientes".

Os pedidos SMART on FHIR a uma loja FHIR têm de cumprir os seguintes requisitos:

  • Forneça a função patient, user ou system nos âmbitos de autorização SMART. Se indicar a função patient, tem de fornecer um contexto do paciente. O contexto do paciente é um ID lógico do recurso Patient. O recurso Patient tem de existir na FHIR store ou existir após o pedido ser feito. Caso contrário, a Cloud Healthcare API rejeita o pedido.

  • Ao criar, ler, atualizar ou eliminar um recurso, o resourceType e o tipo de operação (read ou write) têm de corresponder. Caso contrário, a Cloud Healthcare API rejeita o pedido.

  • Se fornecer um âmbito patient que contenha tipos de recursos não elegíveis para o compartimento do paciente, como patient/Practitioner.*, a verificação de validação do âmbito falha e a Cloud Healthcare API rejeita o âmbito.

  • Pode definir todos os tipos de recursos com o âmbito user. Se um contexto de paciente estiver presente com um âmbito user, os tipos de recursos elegíveis para o compartimento de pacientes estão restritos ao contexto de paciente. Os restantes tipos de recursos ignoram o contexto do paciente.

  • A presença de um contexto de paciente restringe os tipos de recursos elegíveis para o compartimento de pacientes ao paciente indicado. Por exemplo, um recurso Observation tem de ter o campo subject a fazer referência ao recurso Patient fornecido para que o Observation seja acessível. Consulte os tipos de acesso ao compartimento do paciente em Resource CompartmentDefinition - Content para ver uma lista dos campos em cada tipo de recurso de compartimento do paciente que têm de ser referenciados ao paciente indicado para que o recurso seja considerado no compartimento do paciente.

  • Os pedidos podem conter âmbitos patient e user.

  • Não use o âmbito system com o contexto do paciente. Caso contrário, o pedido falha.

  • Não use o âmbito system com o âmbito patient nem o âmbito user.

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