Arquitetura

Arquitetura de Identidade, Autenticação e Autorização com Keycloak

1. Visão Geral

O Medflow utiliza o Keycloak como provedor central de identidade, autenticação, controle de sessão, gerenciamento de credenciais, papéis de acesso e permissões funcionais. Essa decisão foi adotada para separar as responsabilidades de segurança da aplicação das regras de negócio do sistema clínico.

Nesse modelo, o Keycloak é responsável por responder quem é o usuário, como ele se autentica, quais papéis funcionais ele possui e quais ações gerais ele pode executar dentro do sistema. Já o Medflow permanece responsável pelos dados de domínio, como organizações, unidades, consultórios, médicos, agendas, consultas, registros de atendimento e anexos.

A arquitetura adotada evita que a aplicação armazene senhas ou implemente manualmente toda a lógica de autenticação, delegando essa responsabilidade a uma ferramenta especializada. Ao mesmo tempo, preserva no backend do Medflow as regras contextuais que dependem diretamente dos dados da aplicação.

2. Responsabilidades do Keycloak

O Keycloak atua como a camada central de identidade e autorização funcional do Medflow. Suas principais responsabilidades são:

• Autenticar usuários.
• Gerenciar credenciais e senhas.
• Controlar sessões de autenticação.
• Impedir auto-registro público de usuários.
• Aplicar proteção contra tentativas repetidas de login.
• Armazenar dados cadastrais básicos do usuário.
• Gerenciar papéis funcionais.
• Gerenciar grupos de usuários.
• Definir permissões funcionais sobre recursos do sistema.
• Permitir que o backend valide tokens e permissões antes de executar operações protegidas.

Com isso, o Medflow não precisa armazenar senhas em seu banco de dados. A aplicação mantém apenas o identificador externo do usuário, representado pelo sub emitido pelo Keycloak, armazenado localmente como keycloakId.

3. Responsabilidades do Banco do Medflow

O banco de dados do Medflow é responsável por armazenar os dados de domínio da aplicação. Ele não substitui o Keycloak e não é responsável por autenticação ou credenciais.

As principais responsabilidades do banco do Medflow são:

• Armazenar organizações.
• Armazenar unidades e consultórios.
• Registrar o vínculo local entre usuário e organização.
• Armazenar médicos e suas especialidades.
• Armazenar alocações médicas.
• Armazenar agendas e bloqueios de agenda.
• Armazenar consultas e seus status.
• Armazenar registros de atendimento.
• Armazenar anexos vinculados às consultas.
• Preservar histórico e auditoria das entidades por meio do Hibernate Envers.

O banco do Medflow também é responsável por permitir validações contextuais. Por exemplo, o Keycloak pode informar que determinado usuário tem permissão funcional para visualizar consultas, mas somente o banco do Medflow permite verificar se aquela consulta pertence ao usuário autenticado, à organização correta ou ao médico responsável.

4. Responsabilidades do Backend Medflow

O backend atua como ponto de aplicação das regras de segurança e de negócio. Ele integra as informações vindas do Keycloak com os dados armazenados no banco do Medflow.

Suas principais responsabilidades são:

• Receber requisições autenticadas.
• Validar o token de acesso junto ao Keycloak.
• Consultar permissões funcionais no Keycloak.
• Extrair o identificador sub do usuário autenticado.
• Localizar o usuário interno por meio do keycloakId.
• Verificar se o usuário está ativo na organização.
• Validar regras contextuais da aplicação.
• Executar transações de negócio.
• Impedir acessos indevidos mesmo quando o usuário possui permissão funcional genérica.

Dessa forma, o backend valida duas dimensões de segurança:

1. Autorização funcional, definida no Keycloak.
2. Autorização contextual, definida pelas regras de negócio do Medflow.

5. Separação entre Autorização Funcional e Autorização Contextual

A arquitetura do Medflow diferencia autorização funcional de autorização contextual.

A autorização funcional responde à pergunta:

O usuário possui permissão geral para executar esta ação?

Exemplos:

• Pode criar consulta?
• Pode visualizar agenda?
• Pode registrar atendimento?
• Pode criar usuário?
• Pode visualizar relatórios?

Essa camada é controlada pelo Keycloak Authorization Services.

A autorização contextual responde à pergunta:

O usuário pode executar esta ação sobre este dado específico?

Exemplos:

• Este médico pode registrar atendimento nesta consulta?
• Este usuário comum pode visualizar este anexo?
• Esta recepcionista pertence à mesma organização da consulta?
• Esta consulta pertence ao usuário autenticado?
• Este horário está disponível para este médico e consultório?
• Esta entidade está ativa?

Essa camada é controlada pelo backend do Medflow, com base nos dados do banco.

6. Papéis Funcionais

O Medflow utiliza papéis funcionais definidos no client medflow-backend do Keycloak. Esses papéis representam responsabilidades gerais de acesso no sistema.

Os papéis definidos são:

• USUARIO
• ADMINISTRADOR
• RECEPCIONISTA
• MEDICO

O papel USUARIO é o papel base atribuído a todo usuário autenticado do Medflow. Ele representa o usuário comum da aplicação, que pode consultar especialidades, médicos, agendas disponíveis e gerenciar suas próprias consultas.

O papel ADMINISTRADOR representa o usuário responsável pela gestão da organização, incluindo usuários, unidades, consultórios, médicos, especialidades, agendas e relatórios.

O papel RECEPCIONISTA representa o usuário responsável pelo fluxo operacional da clínica, como cadastro de usuários comuns, check-in, reagendamento, cancelamento e acompanhamento da fila.

O papel MEDICO representa o profissional responsável pelo atendimento clínico, visualização da própria agenda, acompanhamento de consultas atribuídas e registro de atendimento.

O papel PACIENTE não foi adotado como role no Keycloak, pois o paciente foi tratado como usuário comum do sistema. Essa decisão reduz redundância e evita criar uma role específica para um comportamento que já é representado pelo acesso básico do usuário autenticado.

7. Grupos de Usuários

Para facilitar a atribuição de papéis, o Keycloak utiliza grupos. Cada grupo recebe uma ou mais roles do client medflow-backend.

Os grupos definidos são:

• USUARIOS
• ADMINISTRADORES
• RECEPCIONISTAS
• MEDICOS

O mapeamento adotado é:

Grupo	Roles atribuídas
USUARIOS	USUARIO
ADMINISTRADORES	USUARIO, ADMINISTRADOR
RECEPCIONISTAS	USUARIO, RECEPCIONISTA
MEDICOS	USUARIO, MEDICO

A opção por scopes genéricos foi adotada para evitar complexidade excessiva no Keycloak. Ações específicas como check-in, cancelamento, reagendamento e finalização são tratadas como atualizações sobre recursos, sendo validadas pelo backend conforme as regras de negócio.

Por exemplo, consulta:update representa a permissão funcional para alterar uma consulta. O backend decide se essa alteração corresponde a cancelamento, reagendamento, check-in, mudança de status ou outra ação permitida.

14. Policies

As policies definem quais papéis funcionais podem satisfazer uma regra de autorização.

Foram criadas policies do tipo Role:

• policy-usuario
• policy-administrador
• policy-recepcionista
• policy-medico

Todas utilizam fetchRoles habilitado, para que o Keycloak consulte as roles atuais do usuário durante a avaliação da política, mantendo o Keycloak como fonte da verdade para papéis e permissões funcionais.

As policies utilizam lógica positiva, ou seja, a presença da role necessária permite satisfazer a política.

15. Permissions

As permissions conectam resources, scopes e policies. Elas indicam quais papéis podem executar determinadas ações sobre determinados recursos.

Exemplos:

• Administradores podem criar, visualizar, atualizar e desativar organizações.
• Recepcionistas podem criar e atualizar usuários comuns, conforme validação do backend.
• Usuários comuns podem criar, visualizar e atualizar suas próprias consultas, conforme validação contextual do backend.
• Médicos podem visualizar e atualizar consultas relacionadas aos seus atendimentos.
• Médicos podem criar, visualizar e atualizar registros de atendimento.
• Administradores podem visualizar relatórios administrativos.

A estratégia de decisão adotada nas permissions é AFFIRMATIVE, permitindo que o acesso seja concedido quando ao menos uma policy aplicável for satisfeita. Essa escolha é importante em permissões compartilhadas por mais de um papel, como permissões de leitura para usuários, recepcionistas e médicos.

16. Policy Enforcement

O modo de enforcement configurado é ENFORCING.

Isso significa que, na ausência de permissão aplicável, o acesso deve ser negado. Essa decisão evita comportamento permissivo por padrão e torna a autorização mais segura.

A configuração geral adotada é:

• Policy Enforcement Mode: ENFORCING
• Decision Strategy: AFFIRMATIVE
• Remote Resource Management: desabilitado

O gerenciamento remoto de recursos foi desabilitado porque os resources, scopes, policies e permissions do Medflow são definidos de forma estática e versionada no realm, não sendo necessário que a aplicação crie recursos dinamicamente no Keycloak.

17. Deleção Física, Desativação Lógica e Status de Fluxo

O Medflow diferencia exclusão física, desativação lógica e alteração de status de fluxo.

A exclusão física, representada pelo scope delete, deve ser exceção. Ela é usada apenas para dados que podem ser removidos sem comprometer a integridade histórica, como alguns anexos ou bloqueios de agenda criados por erro.

A desativação lógica, representada pelo scope deactivate, é usada para entidades estruturais, como organização, usuário, unidade, consultório, especialidade, médico, alocação e agenda. Nesses casos, o registro permanece no banco, mas deixa de ser utilizado em novos fluxos.

Consultas não são apagadas nem desativadas. Elas utilizam status de fluxo, como agendada, confirmada, em espera, em atendimento, finalizada, cancelada ou não compareceu. Essa decisão preserva histórico e integridade do atendimento.

Registros de atendimento também não devem ser removidos fisicamente. Caso seja necessário corrigir informações, a alteração é registrada e auditada pelo Hibernate Envers.

18. Fluxo de Autorização

O fluxo geral de autorização funciona da seguinte forma:

1. O usuário acessa o sistema.
2. O frontend direciona o usuário para autenticação no Keycloak.
3. O Keycloak autentica o usuário e emite um token.
4. O frontend envia o token ao backend.
5. O backend valida o token junto ao Keycloak.
6. O backend verifica se o usuário possui a permissão funcional necessária.
7. O backend localiza o usuário interno pelo keycloakId.
8. O backend valida o vínculo com a organização e o status ativo.
9. O backend aplica regras contextuais do domínio.
10. A operação é executada se todas as validações forem satisfeitas.

Esse fluxo garante que o Keycloak controle permissões funcionais, enquanto o Medflow mantém controle sobre o domínio e os dados específicos da organização.

19. Decisões Arquiteturais

As principais decisões adotadas foram:

• Utilizar Keycloak como provedor central de identidade.
• Não armazenar senhas no banco do Medflow.
• Utilizar o sub do Keycloak como keycloakId no Medflow.
• Utilizar dois clients principais: medflow-frontend e medflow-backend.
• Utilizar Authorization Code Flow com PKCE no frontend.
• Utilizar client confidencial no backend.
• Utilizar Authorization Services para permissões funcionais.
• Remover a role PACIENTE, tratando paciente como usuário comum.
• Utilizar role base USUARIO para todo usuário autenticado.
• Utilizar grupos para facilitar atribuição de roles.
• Utilizar scopes genéricos para simplificar a autorização.
• Manter regras contextuais no backend.
• Manter dados de domínio no banco do Medflow.
• Utilizar desativação lógica para entidades estruturais.
• Utilizar status de fluxo para consultas.
• Utilizar Hibernate Envers para auditoria.
• Versionar a configuração do Keycloak por meio de exportação do realm.

20. Justificativa da Arquitetura

A arquitetura adotada permite separar responsabilidades de forma clara. O Keycloak centraliza autenticação e autorização funcional, reduzindo complexidade de segurança dentro da aplicação. O Medflow mantém controle sobre suas regras de domínio, evitando que dados clínicos e regras contextuais sejam duplicados no provedor de identidade.

Essa separação torna o sistema mais modular, seguro e evolutivo. Novas permissões funcionais podem ser adicionadas no Keycloak, enquanto novas regras de negócio podem ser implementadas no backend sem alterar a estrutura de autenticação. Além disso, a integração com Keycloak aproxima o projeto de práticas utilizadas em sistemas corporativos reais, em que identidade, autenticação e autorização são tratadas por um provedor especializado.