Partilhar via

Visão geral do SMART no 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 o serviço 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 FHIR dos Serviços de Dados de Saúde do Azure é a versão evoluída da API do Azure para FHIR que permite aos clientes gerir serviços FHIR, DICOM e MedTech com integrações noutros serviços do Azure.

Substituiable Medical Applications and Reusable Technologies (SMART on FHIR)® é um padrão de cuidados de saúde através do qual as aplicações podem aceder a informações clínicas através 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. Usar o SMART no FHIR proporciona benefícios importantes, incluindo:

  • As aplicações têm um método conhecido para obter autenticação/autorização para um repositório FHIR.
  • Os utilizadores que acederem a um repositório FHIR com SMART on FHIR são restritos a recursos associados ao utilizador, 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 ainda mais limitado de seus dados usando escopos clínicos SMART.

Os tutoriais a seguir descrevem as etapas para habilitar o SMART em aplicativos FHIR com o Serviço FHIR.

Pré-requisitos

SMART no FHIR usando amostras OSS (SMART no FHIR(Aprimorado))

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

Siga as etapas listadas em Gerenciar usuários: atribuir usuários à função. Qualquer usuário adicionado à função - "FHIR SMART User" é capaz de acessar o Serviço FHIR se suas solicitações estiverem em conformidade com o Guia de implementação do SMART on FHIR, como solicitação com token de acesso, que inclui uma fhirUser reivindicação e uma reivindicação de escopos clínicos. O acesso concedido aos utentes nesta função será limitado pelos recursos associados ao seu fhirUser compartimento e pelas restrições nos âmbitos clínicos.

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

Siga as etapas encontradas em Azure Health Data and AI Samples OSS. Isso permite a integração do servidor FHIR com outros Serviços do Azure (como APIM, funções do Azure e muito mais).

Nota

Os exemplos são código aberto, e você deve revisar 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 Integridade do Azure e não são suportados pelo 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 juntos para demonstrar a conformidade com ONC (g)(10) usando a ID do Microsoft Entra como o fluxo de trabalho do provedor de identidade.

SMART no proxy FHIR

Clique para expandir!

Nota

Este é outro caminho para o SMART no FHIR (Enhanced) como mencionado. A opção SMART on FHIR Proxy permite apenas uma sequência de inicialização EHR.

Para usar o SMART no FHIR, você deve primeiro autenticar e autorizar o aplicativo. Na primeira vez que você usar o SMART no FHIR, você também deve obter consentimento administrativo para permitir que o aplicativo acesse seus recursos 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 que ele 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 for solicitado no aplicativo.) Você pode concluir as mesmas etapas para adicionar outros usuários como proprietários, para que eles possam visualizar e editar o registro deste aplicativo.

Para adicionar a si mesmo ou a outro usuário como proprietário de um aplicativo:

  1. No portal do Azure, aceda a Microsoft Entra ID.
  2. No menu à esquerda, selecione Registro do aplicativo.
  3. Procure o registo da aplicação que criou e, em seguida, selecione-o.
  4. No menu à esquerda, em Gerenciar, selecione Proprietários.
  5. Selecione Adicionar proprietários e, em seguida, adicione a si mesmo ou ao usuário que você deseja ter consentimento de administrador.
  6. Selecione Guardar

Etapa 2: Ativar o SMART no proxy FHIR

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

Para habilitar o proxy SMART no FHIR nas configurações de autenticação para sua instância da API do Azure para FHIR, marque a caixa de seleção SMART no proxy FHIR.

A captura de tela mostra a ativação do SMART no proxy FHIR.

O proxy 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 SMART on FHIR em vez do próprio aplicativo. Em seguida, o proxy 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 Microsoft Entra como uma URL que seja uma combinação da URL de resposta para o proxy SMART on FHIR e a URL de resposta para o aplicativo SMART on FHIR. O URL de resposta combinado assume a seguinte forma.

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

Na resposta, aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA é uma versão codificada em base64 segura para URL do URL de resposta para o aplicativo SMART on FHIR. Para o iniciador de aplicações SMART on FHIR, quando a aplicação está a ser executada localmente, o 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.

A captura de tela mostra como a url de resposta pode ser configurada para o cliente público.

Passo 3: Obter um paciente de teste

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

Etapa 4: Baixe o SMART no inicializador de aplicativos FHIR

O repositório FHIR Server for Azure de código aberto inclui um simples SMART no inicializador de aplicativos FHIR e um exemplo de SMART no aplicativo FHIR. Neste tutorial, use este SMART no iniciador FHIR localmente para testar a configuração.

Você pode clonar o repositório GitHub e ir para 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 você pode definir em appsettings.json:

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

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

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: Testar o SMART no proxy FHIR

Depois de iniciar o iniciador de aplicações SMART on FHIR, pode apontar o seu browser para https://localhost:5001, onde deverá ver o ecrã seguinte.

Screenshot de SMART no iniciador de aplicações FHIR.

Quando você insere as informações do Paciente, do Encontro ou do Médico , observe que o contexto Iniciar é 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 paciente, profissional e muito mais. Esse contexto de inicialização é codificado em base64 e passado para o aplicativo SMART on FHIR como o launch parâmetro de consulta. De acordo com a especificação SMART on FHIR, essa variável é opaca para o aplicativo SMART on FHIR e transmitida ao provedor de identidade.

O proxy 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 processa o aplicativo na tela. O proxy SMART on FHIR suporta os seguintes campos.

  • patient
  • encounter
  • practitioner
  • need_patient_banner
  • smart_style_url

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

Observe que o iniciador de aplicativos SMART on FHIR atualiza as informações de URL de inicialização na parte inferior da página.

Selecione Iniciar para iniciar o aplicativo de exemplo.

Migrar do SMART no FHIR Proxy para o SMART no FHIR (Aprimorado)

Importante

O SMART no proxy FHIR está se aposentando em setembro de 2026, fazendo a transição para o SMART no FHIR (Aprimorado) até essa data. A partir de setembro de 2026, os aplicativos que dependem do proxy SMART on FHIR relatarão erros no acesso ao serviço FHIR.

O SMART no FHIR (Avançado) fornece mais recursos em comparação com o SMART no proxy FHIR. O SMART on FHIR(Enhanced) pode ser considerado para atender aos requisitos com o SMART on FHIR Implementation Guide (v 1.0.0) e §170.315(g)(10) Standardized API for patient and population services criterion. A tabela a seguir lista a diferença entre SMART no proxy FHIR e SMART no FHIR (Aprimorado).

Funcionalidade SMART em FHIR (Melhorado) SMART no proxy FHIR
Suporta lançamento autônomo Sim No
Suporta lançamento de EHR Sim Sim
Suporta restrições de escopo Sim No
Depende de produtos do Azure de primeira parte Sim, os produtos do Azure, como o Azure API Management (APIM), precisam ser integrados Não
Suporte da Microsoft Suportado para o serviço FHIR. O suporte a amostras de código aberto precisa ser relatado e monitorado via GitHub Suportado para o serviço FHIR

Passos da Migração

  • 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 à função de usuário SMART pode acessar o Serviço FHIR, se suas solicitações estiverem em conformidade com o Guia de implementação do SMART on FHIR.
  • Etapa 2: Implantar o exemplo SMART on FHIR em Exemplos de Dados de Saúde do Azure 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 de proxy SMART on FHIR na folha Autenticação para o serviço FHIR.

Se tiver dúvidas, pode esclarecê-las com especialistas da comunidade no Microsoft Q&A. Para suporte técnico, você também pode criar uma solicitação de suporte.

Próximos passos

Agora que você aprendeu sobre como habilitar o SMART na funcionalidade FHIR, consulte a página de exemplos 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

Nota

FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.