Skip to content

Autenticação OIDC e sessão ​

A Fábrica de Cálculos usa sessão de navegador nas aplicações com interface e credenciais conforme o contrato de cada API: chave de API nas rotas públicas de cálculo e JWT Bearer nas superfícies que o exigem. 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.

Chaves nas APIs de cálculo ​

As operações protegidas de tempo, RMI e atrasados exigem a chave no cabeçalho x-api-key. A chave precisa estar válida e possuir o escopo exigido. Uma sessão de navegador ou um token Bearer não substitui essa chave. Os endpoints de referência públicos seguem o que estiver declarado no OpenAPI.

Consulte o guia de APIs para solicitação, retirada e revogação. O cadastro da chave em Authorize, no Swagger, apenas configura o cliente; a validação ocorre quando o servidor recebe uma requisição.

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 de cálculo retornam o envelope público com status, code, messages e result. Em erros, status é error, code é o status HTTP em texto, messages traz as mensagens e result é null. errorCode aparece apenas quando houver código estável específico. Clientes devem considerar tanto o status HTTP quanto esse envelope; não depender de statusMessage do framework.

O tratamento global também preserva o envelope JSON para erros anteriores ao handler, como autenticação e rota inexistente. Uma navegação que peça HTML pode receber uma página de erro em vez de JSON.

  • 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.