Partilhar via

SMART on FHIR

  • Artigo

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 on FHIR fornece, pelo meno,s três benefícios importantes:

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

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

Pré-requisitos

SMART no FHIR usando exemplos dos Serviços de Dados de Saúde do Azure (SMART no 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 utilizador adicionado a esta função poderá aceder ao Serviço FHIR, desde que os seus pedidos estejam em conformidade com o Guia de implementação do SMART on FHIR. O acesso concedido aos utilizadores nesta função será então limitado pelos recursos associados ao seu compartimento fhirUser e pelas restrições nos âmbitos clínicos.

Nota

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 API de leitura 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 neste link para navegar até a solução de código aberto Azure Health Data and AI Samples. As etapas listadas no documento habilitam 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 são usados para demonstrar como os Serviços de Dados de Saúde do Azure (AHDS) e outras ferramentas de código aberto podem ser usados juntos para demonstrar a API padronizada do §170.315(g)(10) para conformidade com os critérios de serviços de pacientes e populações, usando o Microsoft Entra ID como fluxo de trabalho do provedor de identidade.

SMART em FHIR Proxy

Clique para expandir!

Nota

Esta é outra opção para SMART em FHIR (Melhorado) usando as amostras AHDS mencionadas anteriormente. Sugerimos que adote o SMART no FHIR(Enhanced). A opção SMART on FHIR Proxy é uma opção legada. O SMART on FHIR(Enhanced) fornece recursos adicionais ao SMART no proxy FHIR. O SMART on FHIR(Enhanced) atende aos requisitos do SMART on FHIR Implementation Guide (v 1.0.0) e do §170.315(g)(10) Standardized API for patient and population services criterion.

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 para 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 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 do serviço FHIR usa um Audience valor de https://fhir.azurehealthcareapis.com. No entanto, você também pode definir um valor correspondente à URL específica do seu serviço FHIR (por exemplo https://MYFHIRAPI.fhir.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 FHIR, marque a caixa de seleção 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 no FHIR e a URL de resposta para o aplicativo SMART no 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.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.

Passo 3: Obter um paciente de teste

Para testar o serviço FHIR e o proxy 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, 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 inicializador de aplicativos 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.fhir.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.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

Use o seguinte 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 seguinte:

Captura de ecrã a mostrar SMART no iniciador de aplicações FHIR.

Quando você insere as informações do Paciente, Encontro ou Médico , percebe que o contexto Iniciar é atualizado. Quando você está usando o serviço FHIR, o contexto de inicialização é simplesmente um documento JSON que contém informações sobre paciente, médico 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 e você verá algo como o seguinte.

Captura de ecrã a mostrar SMART na aplicação FHIR.

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

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.