Appearance

Autenticação OIDC e sessão ​

A Fábrica de Cálculos separa dois mecanismos de autenticação: sessão de navegador para aplicações com interface e token Bearer para APIs. A separação evita tratar o cookie do usuário como se fosse um token de API e mantém cada borda com validações próprias.

Sessão nas aplicações com interface ​

A camada base-servicos integra as aplicações ao provedor institucional por OAuth 2.0/OpenID Connect (OIDC). O início do fluxo é sempre um redirecionamento; a aplicação não recebe nem verifica credenciais do usuário.

sequenceDiagram
  participant U as Usuário
  participant A as Aplicação
  participant I as Provedor de identidade

  U->>A: GET /auth/iniciar
  A-->>U: Redireciona para /auth ou /auth/silent
  U->>I: Autenticação OIDC
  I-->>A: Retorno OIDC autorizado
  A-->>U: Cria sessão local em cookie HttpOnly
  U->>A: Solicita recurso protegido
  A->>A: Valida a sessão local
  A-->>U: Resposta ou 401/403

O modo interativo permite que o provedor mostre sua tela. O modo silencioso tenta reutilizar uma sessão institucional já existente e retorna à aplicação sem interação quando isso não é possível. Antes do redirecionamento, a aplicação valida o destino de retorno e guarda as opções pendentes do fluxo.

O cookie de sessão é cifrado, marcado como HttpOnly e configurado pela aplicação conforme o ambiente. A renovação usa o token mantido no lado servidor; tokens do provedor não são expostos ao JavaScript da página.

Tokens Bearer nas APIs ​

A camada base-api é responsável pela autenticação das APIs que optam por JWT Bearer. Ela obtém as chaves públicas do provedor via JWKS e valida, de forma estrita:

  • assinatura com RS256, o único algoritmo aceito pela borda Bearer;
  • emissor e audiência;
  • validade temporal;
  • preferred_username, o claim canônico e não configurável usado para identificar o usuário.

A configuração é validada na inicialização da API. Uma API que exige JWT não passa a aceitar acesso anônimo quando essa configuração está ausente ou inválida.

Autorização ​

Autenticar comprova a identidade; não concede automaticamente acesso administrativo. Cada aplicação aplica suas próprias regras depois da autenticação. Assim, uma sessão válida pode receber 403 quando o usuário não possui a autorização exigida para o recurso.

Contrato de erro ​

As APIs Nuxt/Nitro usam o formato de erro nativo do framework. Clientes devem considerar o status HTTP e extrair a mensagem de statusMessage ou message.

  • 401 indica ausência ou invalidade da autenticação exigida;
  • 403 indica identidade válida sem autorização para a operação;
  • falhas de configuração ou indisponibilidade essencial permanecem erros de servidor, sem fallback anônimo.

Veja o portal de APIs para saber qual mecanismo cada endpoint público exige.