Gateway / BFF (Token Handler Pattern)

Autorização centralizada entre as SPAs do FUJI (web, alunos, loja) implementada com o padrão BFF / Token Handler, evitando expor o token do Keycloak ao JavaScript do navegador.

Motivação

Uma tentativa anterior usava um Service Worker no SPA para interceptar chamadas e injetar o token. Essa abordagem foi rejeitada e revertida: o escopo de um Service Worker é por origem/locale e não cobria rotas como /loja; os backends consumidos são cross-origin (api.fuji.net.br, store.fuji.net.br); e o token do Keycloak passa de 4KB, inviável de manter em cookie sem um componente intermediário. Em seu lugar foi adotado o padrão BFF (Backend For Frontend) / Token Handler.

Arquitetura

gateway-bff

  • oauth2-proxy: expõe /oauth2/start (login) e /oauth2/sign_out (logout), mantém a sessão OIDC no Redis e devolve ao navegador um cookie _fuji_session (HttpOnly, ticket pequeno — resolve o problema do token Keycloak ultrapassar 4KB).

  • gw-internal (Envoy): converte o X-Forwarded-Access-Token recebido do oauth2-proxy em header Authorization: Bearer, aplica CORS e reescreve rotas (/v1/→/api/, /v2/→/v2/, /userinfo→/v2/profile). Rotas /v1/public e / são pass-through, sem autenticação.

  • Passthrough deliberado: o backend continua validando o JWT normalmente (via CustomKeycloakAuthentication) mesmo recebendo o token já resolvido pelo gateway — remover essa validação redundante do backend é um passo futuro, para reduzir risco na adoção.

  • Whitelist de backends acessíveis via BFF é derivada do conf.json do frontend (apiEndpoint/api_v2/api_store).

As rotas /login e /logout do oauth2-proxy não fazem login/logout — são rotas protegidas genéricas que redirecionam ao authorize do Keycloak (re-autenticando silenciosamente via SSO). Usar /logout para encerrar sessão é um erro comum: o usuário volta autenticado. Usar sempre /oauth2/start e /oauth2/sign_out.

Status

Em produção no ambiente de desenvolvimento (gitops/dev-fuji/gateway/) e validado no ambiente local. Ver Repositório dedicado do Gateway (bff) para como a configuração do gateway é gerada e publicada.