Desenvolvendo SMART em aplicações FHIR com Auth0 e InterSystems IRIS FHIR Server - Configuração

No último artigo nós apresentamos a arquitetura do nosso projeto SMART On FHIR, então agora é o momento de colocar a mão na massa e começar a configurar os elementos que vamos precisar. 

Vamos começar com Auth0.

Configuração AUTH0

Vamos começar criando uma conta Auth0 com um email válido. Uma vez registrada, vamos criar nossa primeira aplicação e faremos isso do menu a esquerda:

Em nosso exemplo, a aplicação será do tipo Single Page Web Application, como é uma aplicação desenvolvida em Angular 16. Selecionamos esta opção e clicamos em Create.

Na próxima pagina devemos definir os seguintes campos:

• Allowed Callback URLs: https://localhost
• Allowed Logout URLs: https://localhost
• Allowed Web Origins: https://localhost
• Allow Cross-Origin Authentication: Marcado
• Allowed Origins (CORS): https://localhost

ATENÇÃO! URLs devem ser HTTPS, é uma das necessidades para conexões OAuth2

Com isso temos configuradas as URLs que o Auth0 necessita para redirecionar o usuário após os processos de autenticação e autorização. Se você vir as URLs, elas não têm nenhuma porta definida. Isso é porque com a entrega do projeto Angular no Docker por meio do NGINX, indicamos que será acessível pela porta default HTTPS, 443. Você pode colocar o nome que preferir.

Para as configurações subsequentes de nosso projeto Angular, escreva os valores que achamos tanto no Domain quanto no Client ID.

Com nossa aplicação configurada, é hora de definir a API que vai receber as requisições da nossa aplicação Angular e de novo faremos isso pelo menu à esquerda:

Essa opção nos mostra uma nova tela para entrar com todos os dados necessários:

Você vai precisar definir um identificador para a API que posteriormente será usado pela aplicação Angular como um "ambiente" para conectar corretamente. Como você pode ver, eles recomendam que você insira uma URL, mas não é necessário que essa URL seja funcional, já que só vai ser usada como um identificador. No nosso caso, podemos definir:

https://localhost/smart/fhir/r5

Finalmente, configuamos o algoritmo de assinatura para RS256 e vamos à aba de Permissões, onde definimos o escopo do FHIR para usuários conectados:

Se você quiser ir mais a fundo no tópico de contextos FHIR, você pode consultar a URL da página oficial clicando aqui. Para o nosso exemplo, definimos o escopo user/*.*  que permite que o usuário validado performe operações CRUD em todos os recursos do servidor FHIR.

Perfeito! Nós já configuramos nossa conta Auth0 para funcionar como um servidor OAuth2.

Configuração Angular app

Eu gostaria de ter desenvolvido a aplicação em Angular 17, que introduz algumas mudanças, mas infelizmente a documentação associada para Auth0 e suas livrarias só estão disponíveis para Angular 16, então eu decidi seguir o caminho mais fácil e desenvolvi na versão 16.

Para configurar nosso projeto Angular, vamos precisar abrir a página app.module.ts e procurar o seguinte fragmento de código:

Vamos ver o que cada parâmetro a configurar significa:

• domain: corresponde ao valor Domain que foi gerado quando criamos nossa aplicação em Auth0.
• clientId: o mesmo que acima, mas com o valor gerado Client ID
• audience: correspondente à URL que configuramos como identificador da nossa API.
• uri: com esse valor, vamos dizer à livraria Auth0 TypeScript para interceptar todas as chamadas que fizermos à URLs que contém essa URI e incluir o Acess_token que Auth0 vai retornar quando validarmos (adicionando o parâmeto de Authorização para a header a chamada: Bearer ...).

Uma vez que esses valores fossem modificados, teríamos nossa aplicação Angular configurada para funcionar com Auth0. No próximo artigo vamos ver em mais detalhes como invocar um Auth0 da nossa interface de usuário.

Configuração InterSystems IRIS for Health 

Esse projeto é configurado para instalar automaticamente o servidor FHIR durante o processo de desenvolvimento, isso vai nos salvar um passo. No nosso caso, temos definida a URI /smart/fhir/r5 como endpoint do nosso servidor FHIR. Para aqueles que não estão familiarizados com a terminologia FHIR, r5 se refere À versão mais recente do FHIR, disponível há alguns meses no IRIS.

Para configurar nossa instância IRIS, precisaremos primeiro iniciar nosso Docker e entregar os 3 containers disponíveis no projeto. Precisaremos primeiro executar o comando a seguir no terminal a partir da raiz do projeto:

docker-compose up -d --build

Isso faz com que possamos construir e rodar os containers presentes no projeto. Para usuários Windows, se você usa o Docker Desktop você deve ver uma tela como a seguinte:

Aqui nós temos 3 containers:

• iris: com a instância IRIS onde nosso servidor FHIR está localizado.
• smart-ui: com o código de nossa aplicação web entregue via NGINX configurada de tal maneira que todas as conexões são por SSL com seus certificados associados.
• webgateway: com esse servidor associado Apache (lembre que desde a versão oficial 2023.1 o Private Web Server foi eliminado, embora esteja ainda disponível nas versões de comunidade).

Web Gateway

Como eu venho repetindo, para usar o OAuth2 com nosso servidor FHIR, é obrigatório que todas as conexões sejam feitas por HTTPS, então o servidor Apache deve ser configurado para aceitar apenas chamadas desse tipo. Se você der uma olhada no arquivo /webgateway/shared/CSP.conf você poderá ver a seção a seguir responsável por configurar o servidor Apache:

# SSL SECTION #
# Enable SSL/TLS (https://) on the Apache web server.
# The user is responsible for providing valid SSL certificates.
LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so
LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile "/webgateway-shared/apache_webgateway.cer"
SSLCertificateKeyFile "/webgateway-shared/apache_webgateway.key"
Header add ACCESS-CONTROL-ALLOW-ORIGIN "*"
</VirtualHost>

Você pode ver como está configurada de tal maneira que as chamadas somente venham pela porta 443, ou seja, a URL do nosso webgateway será https://webgatwaye as chamadas que lançamos da nossa aplicação web ao nosso servidor FHIR devem ser redirecionadas a essa URL (webgateway é a máscara dada à network do container Docker criada por ele).

Todas as chamadas ao servidor do Angular chegarão com a URL https://localhost/smart/fhir/r5 e o NGINX terá a função de redirecionar esse localhost ao webgateway. Se você abrir o arquivo /smart-ui/nginx.conf você poderá ver a seguinte configuração:

 

Nessa configuração, vemos que nossa aplicação web ouvirá a porta 443 e todas as chamadas que têm o valor / na URL serão manuseadas pela aplicação Angular, enquanto aquelas que incluem /smart/ serão redirecionadas ao https://webgateway.

Be careful with proxy_set_header, which will be the value that avoids headaches with CORS. To prevent our Web Gateway from rejecting calls from other servers, we must modify the value of the Host header to configure it with the address of the Web Gateway.

InterSystems IRIS

Agora precisamos configurar nosso IRIS para funcionar com Auth0. Para isso vamos configurá-lo como um cliente Oauth2. E para isso, só precisaremos acessar o Portal de Administração com as credenciais superuser/SYS e acessar a opção Administração do Sistema > Segurança > OAuth 2.0 > Cliente, então clicar em Criar Descrição do Servidor e preencher o endpoint Issuer com o valor de domínio que obtivemos criando a aplicação para Auth0 (https://[MY_DOMAIN]/). Cuidado! A URL deve terminar com "/". Finalmente selecionamos a configuração SSL/TLS e clicamos em Descobrir e Salvar:

Automaticamente nossa instância IRIS vai retornar as informações que precisa do Auth0:

Nós só precisamos adicionar um cliente ao servidor que acabamos de configurar. Ao clicar em Client Configuration vamos acessar uma nova tela onde podemos definir o nome da aplicação e do cliente. Esse nome de cliente será o que posteriormente vamos usar para configurar nosso servidor FHIR.

Servidor FHIR

O último passo para finalizar a configuração do nosso projeto é dizer ao servidor FHIR qual cliente OAuth2 será usado para a conexão. Para acessar a configuração vamos abrir o Portal de Administração e selecionar Health > FHIR > FHIR Configuration > Server Configuration  e então vamos abrir o endpoint mostrado na tela. Vamos para o final dele e clicaremos em Editar. Finalmente, adicionamos no campo OAuth Client Name o nome com o qual criamos a configuração do cliente.

Conclusão

Bom, já temos nosso projeto configurado, no próximo artigo vamos ver como a aplicação Angular interopera com cada um dos atores.

Obrigado pela sua atenção!