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.
401indica ausência ou invalidade da autenticação exigida;403indica 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.