Compartilhar via

Visão geral do SMART on FHIR

  • Artigo

Importante

A API do Azure para FHIR será desativada em 30 de setembro de 2026. Siga as estratégias de migração para fazer a transição para FHIR® dos Serviços de Dados de Saúde do Azure até essa data. Devido à desativação da API do Azure para FHIR, novas implantações não serão permitidas a partir de 1º de abril de 2025. O serviço dos Serviços de Dados de Saúde do Azure para serviço FHIR é a versão evoluída da API do Azure para FHIR que permite aos clientes gerenciar os serviços FHIR, DICOM e serviço de tecnologia médica com integrações a outros serviços do Azure.

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 com base em padrões abertos, incluindo OAuth2 e OpenID Connect, às interfaces FHIR para habilitar a integração com sistemas EHR. O uso do SMART on FHIR oferece benefícios importantes, incluindo:

  • 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 mais limitado de seus dados usando escopos clínicos SMART.

Os tutoriais a seguir descrevem etapas para habilitar aplicativos SMART on FHIR com o serviço FHIR.

Pré-requisitos

SMART on FHIR usando OSS de exemplos (SMART on FHIR(Avançado))

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

Siga as etapas listadas em Gerenciar usuários: atribuir usuários a funções. Qualquer usuário adicionado à função – "Usuário FHIR SMART" poderá acessar o serviço FHIR se as solicitações dele estiverem em conformidade com o Guia de implementação SMART on FHIR, como a solicitação contendo um token de acesso, que inclui uma declaração fhirUser e uma declaração de escopos clínicos. 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.

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

Siga as etapas descritas no software de código aberto de amostras dos Serviços de Dados de Saúde do Azure e IA. Isso habilita a integração do servidor FHIR com outros serviços do Azure (como APIM, Azure Functions 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 podem ser usados para demonstrar como os Serviços de Dados de Saúde do Azure e outras ferramentas de código aberto podem ser usados em conjunto para demonstrar a conformidade com ONC (g)(10), usando o Microsoft Entra ID como fluxo de trabalho do provedor de identidade.

Proxy da SMART on FHIR

Clique para expandir.

Observação

Este é outro caminho para o SMART on FHIR (Avançado), conforme mencionado. A opção de Proxy SMART on FHIR habilita apenas a sequência de inicialização do EHR.

Para usar o SMART on FHIR, primeiro você deve autenticar e autorizar o aplicativo. Na primeira vez que usar o SMART on FHIR, você também deve 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 do administrador para si mesmo mais tarde quando for solicitado no aplicativo.) Você pode concluir as mesmas etapas para adicionar outros usuários que os proprietários, para que eles possam exibir e editar esse registro de 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 da API do Azure para FHIR usa um valor Audience de https://azurehealthcareapis.com. No entanto, você também pode definir um valor correspondente à URL específica do serviço FHIR (por exemplo https://MYFHIRAPI.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.

A captura de tela mostra a habilitação do proxy 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 essa retransmissão de duas etapas do código de autenticação, você precisa definir a URL de resposta (retorno de chamada) para seu aplicativo cliente do Microsoft Entra para uma URL que seja uma combinação da URL de resposta para o proxy do SMART on FHIR e a URL de resposta para o aplicativo SMART on 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.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.

Captura de tela mostrando como a URL de resposta pode ser configurada para o cliente público.

Etapa 3: obtenha um paciente de teste

Para testar a API do Azure para FHIR e o proxy do SMART on FHIR, você precisa ter pelo menos um paciente no banco de dados. Se você ainda não tiver interagido com a API e não tiver dados no banco de dados, consulte Como acessar 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. Neste tutorial, use esse iniciador do SMART on FHIR localmente para testar a instalaçã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.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

Recomendamos o uso do recurso dotnet user-secrets.

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

Use este comando para executar o aplicativo.

dotnet run

Etapa 5: teste o proxy do SMART on FHIR

Depois de iniciar o inicializador de aplicativos SMART on FHIR, você pode apontar seu navegador para https://localhost:5001, em que deverá ver a tela a seguir.

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

Ao inserir informações de Paciente, Consulta ou Profissional, você observará que o Contexto de inicialização é atualizado. Quando você está usando a API do Azure para 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 on 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.

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.