Compartilhar via

SMART on FHIR

  • Artigo

Aplicativos médicos substituíveis e tecnologias reutilizáveis (SMART on FHIR) é um padrão de saúde por meio do qual os aplicativos podem acessar informações clínicas por meio de um armazenamento de dados. Ele adiciona uma camada de segurança baseada em padrões abertos, incluindo OAuth2 e OpenID Connect, às interfaces FHIR® para permitir a integração com sistemas EHR. O uso do SMART on FHIR oferece pelo menos três benefícios importantes:

  • Os aplicativos têm um método conhecido para obter autenticação/autorização em um repositório FHIR.
  • Os usuários que acessam um repositório FHIR com o SMART on FHIR são restritos aos recursos associados ao usuário, em vez de ter acesso a todos os dados no repositório.
  • Os usuários têm a capacidade de conceder aos aplicativos acesso a um conjunto limitado de seus dados usando escopos clínicos SMART.

Os tutoriais a seguir fornecem etapas para habilitar o SMART em aplicativos FHIR com o FHIR Service.

Pré-requisitos

SMART on FHIR usando Amostras dos Serviços de Dados de Saúde do Azure (SMART on FHIR (Avançado))

Etapa 1: Configurar a função de usuário FHIR SMART

Siga as etapas listadas na seção Gerenciar usuários: atribuir usuários à função. Qualquer usuário adicionado a essa função poderá acessar o Serviço FHIR, desde que suas solicitações estejam em conformidade com o Guia de implementação SMART no FHIR. O acesso concedido aos usuários nessa função será limitado pelos recursos associados ao compartimento fhirUser e pelas restrições nos escopos clínicos.

Observação

O Guia de Implementação do SMART on FHIR define o acesso aos tipos de recursos FHIR com escopos. Esses escopos afetam o acesso que um aplicativo pode ter aos recursos FHIR. Um usuário com a função de usuário SMART tem acesso para executar interações de leitura de API no serviço FHIR. A função de usuário SMART não concede acesso de gravação ao serviço FHIR.

Etapa 2: integração do servidor FHIR com amostras

Clique nesse link para navegar até a solução de código aberto Azure Health Data e AI Samples. As etapas listadas no documento permitem a integração do servidor FHIR com outros serviços do Azure (como APIM, funções do Azure e muito mais).

Observação

Os amostras são código de software livre e você deve examinar as informações e os termos de licenciamento no GitHub antes de usá-lo. Eles não fazem parte do Serviço de Dados de Saúde do Azure e não têm suporte do Suporte da Microsoft. Esses exemplos são usados ​​para demonstrar como o Serviços de Dados de Saúde do Azure (AHDS) e outras ferramentas de código aberto podem ser usados ​​juntos para demonstrar a conformidade com o critério §170.315(g)(10) API padronizada para serviços de pacientes e população, usando o Microsoft Entra ID como o fluxo de trabalho do provedor de identidade.

Proxy do SMART on FHIR

Clique para expandir.

Observação

Essa é outra opção para SMART no FHIR (Aprimorado) usando os exemplos AHDS mencionados anteriormente. Sugerimos que você adote o SMART on FHIR(Avançado). A opção SMART no FHIR Proxy é uma opção legada. O SMART no FHIR (aprimorado) fornece recursos adicionais ao proxy SMART no FHIR. SMART no FHIR (Aprimorado) atende aos requisitos do Guia de implementação SMART no FHIR (v 1.0.0) e §170.315(g)(10) API padronizada para critério de serviços de pacientes e população.

Para usar o SMART on FHIR, primeiro você deve autenticar e autorizar o aplicativo. Na primeira vez que você usar o SMART no FHIR, você também deverá obter consentimento administrativo para permitir que o aplicativo acesse seus recursos do FHIR.

Se você não tiver uma função de propriedade no aplicativo, entre em contato com o proprietário do aplicativo e peça a ele que conceda consentimento de administrador para você no aplicativo.

Se você tiver privilégios administrativos, conclua as etapas a seguir para conceder consentimento de administrador diretamente a si mesmo. (Você também pode conceder consentimento de administrador a si mesmo mais tarde, quando solicitado no aplicativo.) Você pode usar essas mesmas etapas para adicionar outros usuários como proprietários, para que eles possam visualizar e editar o registro do aplicativo.

Para adicionar você ou outro usuário como proprietário de um aplicativo:

  1. No portal do Azure, acesse Microsoft Entra ID.
  2. No menu à esquerda, selecione Registro de Aplicativo.
  3. Pesquise o registro de aplicativo que você criou e selecione-o.
  4. No menu esquerdo, em Gerenciar, selecione Usuários.
  5. Selecione Adicionar proprietáriose adicione a si mesmo ou ao usuário que você deseja ter o consentimento do administrador.
  6. Selecione Salvar

Etapa 2: habilite o proxy do SMART on FHIR

O SMART on FHIR requer que Audience tenha um URI de identificador igual ao URI do serviço FHIR. A configuração padrão do serviço FHIR usa um valor Audience de https://fhir.azurehealthcareapis.com. No entanto, você também pode definir um valor correspondente à URL específica do serviço FHIR (por exemplo https://MYFHIRAPI.fhir.azurehealthcareapis.com). Isso é necessário ao trabalhar com o proxy do SMART on FHIR.

Habilite o proxy do SMART on FHIR nas configurações de Autenticação para a instância da API do Azure para FHIR marcando a caixa de seleção proxy do SMART on FHIR.

O proxy do SMART on FHIR atua como um intermediário entre o aplicativo SMART on FHIR e o Microsoft Entra ID. A resposta de autenticação (o código de autenticação) deve ir para o proxy do SMART on FHIR, em vez do próprio aplicativo. O proxy então encaminha a resposta para o aplicativo.

Devido a esse retransmissão em duas etapas do código de autenticação, você precisa definir a URL de resposta (retorno de chamada) para seu aplicativo cliente Microsoft Entra como uma URL que seja uma combinação da URL de resposta para o proxy SMART no FHIR e da URL de resposta para o aplicativo SMART no FHIR. O URL de resposta combinado assume o seguinte formato.

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

Na resposta, aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA é uma versão codificada em base64 e segura para URL do URL de resposta do aplicativo SMART no FHIR. Para o inicializador de aplicativos SMART on FHIR, quando o aplicativo está em execução localmente, a URL de resposta é https://localhost:5001/sampleapp/index.html.

Você pode gerar a URL de resposta combinada usando um script como o seguinte.

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.fhir.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

Adicione a URL de resposta ao aplicativo cliente público que você criou anteriormente para o Microsoft Entra ID.

Etapa 3: obtenha um paciente de teste

Para testar o serviço FHIR e o proxy do SMART on FHIR, você precisa ter pelo menos um paciente no banco de dados. Se você ainda não usou a API e não tem dados no banco de dados, veja Acesse o serviço FHIR usando o Postman para carregar um paciente. Anote a ID de um paciente específico.

Etapa 4: baixe o inicializador de aplicativos do SMART on FHIR

O servidor FHIR para o repositório do Azure de software livre inclui um inicializador de aplicativos SMART on FHIR simples e um aplicativo de exemplo SMART on FHIR. Nesse tutorial, use o iniciador de aplicativo SMART no FHIR localmente para testar a configuração.

Você pode clonar o repositório GitHub e acessar o aplicativo usando os seguintes comandos.

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

O aplicativo precisa de algumas definições de configuração, que podem ser feitas em appsettings.json:

{
    "FhirServerUrl": "https://MYFHIRAPI.fhir.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

Recomendamos que você use o recurso dotnet user-secrets:

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Use o seguinte comando para executar o aplicativo:

dotnet run

Etapa 5: teste o proxy do SMART on FHIR

Depois de iniciar o iniciador do aplicativo SMART no FHIR, você pode apontar seu navegador para https://localhost:5001, onde deverá ver o seguinte:

Captura de tela mostrando o SMART no inicializador de aplicativos FHIR.

Ao inserir informações de Paciente, Encontro ou Profissional, você observará que o Contexto de inicialização é atualizado. Ao suar o serviço FHIR, o contexto de inicialização é simplesmente um documento JSON que contém informações sobre pacientes, profissionais e muito mais. Esse contexto de inicialização é codificado em Base64 e passado para o aplicativo SMART on FHIR como o parâmetro de consulta launch. De acordo com a especificação do SMART on FHIR, essa variável é opaca para o aplicativo SMART on FHIR e passada para o provedor de identidade.

O proxy do SMART on FHIR usa essas informações para preencher campos na resposta do token. O aplicativo SMART no FHIR pode usar esses campos para controlar para qual paciente ele solicita dados e como ele renderiza o aplicativo na tela. O SMART no proxy FHIR oferece suporte aos seguintes campos.

  • patient
  • encounter
  • practitioner
  • need_patient_banner
  • smart_style_url

Esses campos destinam-se a fornecer orientação para o aplicativo, mas não transmitem nenhuma informação de segurança. Um aplicativo SMART on FHIR pode ignorá-los.

Observe que o inicializador de aplicativos SMART on FHIR atualiza as informações da URL de inicialização na parte inferior da página. Selecione Iniciar para iniciar o aplicativo de exemplo e você deverá ver algo como o seguinte.

Captura de tela mostrando o SMART no aplicativo FHIR.

Inspecione a resposta do token para ver como os campos de contexto de inicialização são passados para o aplicativo.

Migrar do Proxy do SMART on FHIR para o SMART on FHIR (Avançado)

Importante

O proxy do SMART on FHIR será desativado em setembro de 2026, fazendo a transição para o SMART on FHIR (Avançado) até essa data. A partir de setembro de 2026, os aplicativos que dependem do proxy do SMART on FHIR relatarão erros ao acessar o serviço FHIR.

O SMART on FHIR (Avançado) fornece mais recursos em comparação com o proxy do SMART on FHIR. O Smart on FHIR(Avançado) pode ser considerado para atender aos requisitos com o Guia de Implementação SMART on FHIR (v 1.0.0) e a API Padronizada do §170.315(g)(10) para critério de serviços de pacientes e de população. A tabela a seguir lista a diferença entre o proxy do SMART on FHIR e o SMART on FHIR (Avançado).

Funcionalidade SMART on FHIR (Avançado) Proxy da SMART on FHIR
Dá suporte à Inicialização Autônoma Sim Não
Dá suporte à Inicialização EHR Sim Yes
Dá suporte a restrições de escopo Sim Não
Depende de produtos proprietários do Azure Sim, os produtos do Azure, como o Gerenciamento de API do Azure (APIM), precisam ser integrados Não
Suporte da Microsoft O suporte a amostras de código aberto do serviço FHIR precisa ser relatado e monitorado por meio do GitHub Com suporte para o serviço FHIR

Etapas da Migração

  • Etapa 1: configure a função de usuário do FHIR SMART. Siga as etapas listadas na seção Gerenciar Usuários: Atribuir Usuários à Função. Qualquer usuário adicionado à função de usuário do SMART poderá acessar o Serviço FHIR, se suas solicitações estiverem em conformidade com o Guia de implementação do SMART on FHIR.
  • Etapa 2: implante a amostra do SMART on FHIR em amostras de Azure Health Data e AI OSS
  • Etapa 3: atualize o ponto de extremidade da URL do serviço FHIR para "{{BASEURL_FROM_APIM}}/smart."
  • Etapa 4: desmarque a configuração do proxy do SMART on FHIR na folha Autenticação do serviço FHIR.

Se você tiver dúvidas, confira respostas da Microsoft e de especialistas da comunidade em Microsoft Q&A. Para obter suporte técnico, você também pode criar uma solicitação de suporte.

Próximas etapas

Agora que você aprendeu como habilitar a funcionalidade do SMART on FHIR, consulte a página de amostras de pesquisa para obter detalhes sobre como pesquisar usando parâmetros de pesquisa, modificadores e outros métodos de pesquisa FHIR.

Exemplos de pesquisa FHIR

Observação

FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.