Conectar-se a aplicativos usando o SMART no FHIR

Esta página descreve como usar o padrão SMART (Substitutable Medical Applications, Reusable Technologies) no FHIR v1.1.0 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 registro de integridade eletrônica (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, poderá 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 oferece suporte aos modelos de autorização do OpenID e do OAuth 2.0 para autorização e autenticação.

Framework de inicialização do aplicativo SMART, escopos e contexto de inicialização

A API Cloud Healthcare oferece suporte ao framework de inicialização do aplicativo SMART, aos escopos e ao 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 de um sistema de EHR existente ou de uma sessão de portal de pacientes, ambos chamados de "inicialização 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 de inicialização

Descreve o paciente, a consulta 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 o 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 do 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 represente os escopos de autorização SMART concedidos e o contexto do paciente, a API Cloud Healthcare não vai 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 os escopos de autorização do 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ão transmitidos apenas 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 fornecido. 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, é necessário configurar 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 JWT SMART. 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 SMART JWT, use o acelerador de interoperabilidade baseado na Apigee HealthAPIx na Apigee para configurar um servidor de autenticação que assine 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 o 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 em Configurar uma conta de serviço do Google Cloud.

O SMARTProxy é um proxy de código aberto do Google que oferece 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ões 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 pelo 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. A API Cloud Healthcare retorna uma resposta pelo SMARTProxy para o cliente.

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, eles vão usar 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 vão registrar seu endereço de e-mail como o endereço principal. Quando você usa um proxy para chamar a API Cloud Healthcare, ele 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. Assim, 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 é necessário configurar o armazenamento FHIR que armazena os dados FHIR que você está acessando.

Fazer solicitações SMART no 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 do 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 que a solicitação solicita.

O compartimento do paciente é fundamental para a lógica de aplicação do 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".

As solicitações SMART no FHIR para um armazenamento FHIR precisam 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 é um ID lógico de recurso do paciente. O recurso de paciente já precisa existir no armazenamento FHIR ou depois que a solicitação for feita. Caso contrário, a API Cloud Healthcare vai rejeitar a solicitação.

  • Ao criar, ler, atualizar ou excluir um recurso, os resourceType e o tipo de operação (read ou write) precisam corresponder. Caso contrário, a API Cloud Healthcare vai 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 o contexto do paciente estiver presente com um escopo user, os tipos de recurso 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 ter o campo subject para referenciar o recurso de paciente fornecido para que a observação seja acessível. Consulte os tipos de acesso ao compartimento do paciente em Compartimento de recursos: conteúdo para uma lista de quais campos em cada tipo de recurso do compartimento do paciente precisam ser referenciados ao paciente específico para que o recurso seja considerado dentro do compartimento.

  • 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.