Auth Visualizer

Auth Visualizer é uma demo local para estudar autenticação moderna com OIDC, Keycloak, Authorization Code Flow com PKCE, Bearer token, refresh token e validação de JWT no backend.

O projeto foi feito para tornar visível um fluxo que normalmente fica escondido entre navegador, frontend, provedor de identidade e API. Ele mostra quando o usuário é redirecionado para login, quando o código de autorização volta para a SPA, quando o token é anexado na requisição, como o backend valida assinatura, issuer e expiração, e como a autorização por role decide se a rota pode executar.

O que o projeto faz

O repositório contém uma aplicação de tarefas protegida por login e um painel visual separado:

• front-sample: SPA Vue 3 + Vite que usa keycloak-js para login, cadastro, logout, refresh de token e chamadas autenticadas para a API.
• back-sample: API Bun/TypeScript que valida o access token JWT com jose, consulta as chaves públicas JWKS do Keycloak e exige a role user antes de manipular tarefas.
• visualizer: SPA Vue 3 + Vite que escuta eventos via Server-Sent Events e desenha o caminho das ações entre Frontend, Keycloak e Backend.
• keycloak: configuração exportada do realm local auth-visualizer, com client front-sample, roles e usuários de demonstração.
• docker-compose.yml: sobe o Keycloak local com importação automática do realm.

As tarefas ficam em memória no backend, separadas por usuário autenticado. Ao reiniciar o backend, os dados são perdidos.

Para que foi feito

Este código foi criado como material didático para entender e demonstrar uma migração de autenticação baseada em sessão para um fluxo OIDC com tokens.

Ele ajuda a responder perguntas como:

• Onde o login realmente acontece?
• O frontend guarda senha ou apenas redireciona para o provedor de identidade?
• O que volta para a aplicação depois do login?
• Onde ficam access token, refresh token e ID token?
• Por que o backend precisa validar o JWT mesmo que o frontend já esteja logado?
• Como o backend escolhe a chave pública correta usando o kid do JWT?
• Qual a diferença entre autenticação, autorização e refresh de token?

Arquitetura

Browser/Frontend -> Keycloak -> Frontend -> Backend API -> Keycloak JWKS
        |                                              |
        +---------------- visualizer events -----------+

O fluxo real de segurança acontece entre frontend, Keycloak e backend. O visualizer apenas recebe eventos observáveis para fins de aprendizado; ele não participa da decisão de autenticação ou autorização.

Serviços locais

Serviço	Porta	Descrição
Keycloak	http://localhost:8080	Provedor de identidade local
Backend	http://localhost:3001	API de tarefas protegida por JWT
Frontend	http://localhost:5173	App de tarefas com login OIDC
Visualizer	http://localhost:5174	Diagrama vivo dos eventos de autenticação

Requisitos

• Docker e Docker Compose
• Bun

Como rodar

Suba o Keycloak:

docker compose up keycloak

Em outro terminal, rode o backend:

cd back-sample
bun install
bun run dev

Em outro terminal, rode o app de tarefas:

cd front-sample
bun install
bun run dev

Em outro terminal, rode o visualizador:

cd visualizer
bun install
bun run dev

Depois abra:

• To-do app: http://localhost:5173
• Visualizer: http://localhost:5174
• Admin do Keycloak: http://localhost:8080

Usuários de demo

• admin / admin: possui roles admin e user
• user / user: possui role user

Use qualquer um dos dois usuários para acessar a lista de tarefas. A API exige a client role user, então o backend valida o JWT, extrai roles de resource_access[front-sample].roles e só depois executa a ação.

Endpoints principais

• GET /health
• GET /api/todos
• POST /api/todos
• PATCH /api/todos/:id
• DELETE /api/todos/:id
• GET /events
• GET /events/history
• POST /events/reset
• POST /events/client

Tokens

O frontend não salva access token, refresh token ou authorization code em localStorage.

Nesta demo, keycloak-js mantém os tokens em memória. Antes de cada chamada protegida, o frontend executa keycloak.updateToken(10).

Isso significa que:

• se o access token ainda é válido por mais de 10 segundos, o frontend reutiliza o token atual;
• se ele está perto de expirar, keycloak-js pede um novo token ao Keycloak;
• se a sessão no Keycloak expirou, o refresh falha e o usuário precisa fazer login novamente.

O backend nunca renova tokens. Ele apenas valida o access token recebido no header Authorization: Bearer. Se o token estiver ausente, expirado ou inválido, o backend retorna 401 Unauthorized.

Testar refresh mais rápido

Para ver refresh token em ação sem esperar muito:

1. Abra o admin do Keycloak em http://localhost:8080.
2. Entre com admin / admin.
3. Selecione o realm auth-visualizer.
4. Vá em Realm settings -> Tokens.
5. Reduza Access Token Lifespan para algo como 30 seconds.
6. Salve, volte ao to-do app e faça chamadas à API observando o visualizer.

Observações de segurança

Esta é uma demo local de aprendizado. O visualizer exibe metadata crua quando disponível, incluindo access token, refresh token, ID token, authorization code e header Authorization.

Isso é intencional para facilitar o estudo do fluxo, mas não deve ser usado assim em ambientes compartilhados, staging ou produção. Em sistemas reais, esses campos devem ser omitidos, mascarados ou nunca enviados para telemetria.

Licença

Este projeto está licenciado sob a licença MIT, uma licença permissiva de uso livre. Você pode usar, copiar, modificar, distribuir e adaptar o código, inclusive em projetos pessoais ou comerciais, desde que mantenha o aviso de copyright e a permissão da licença.

Veja o texto completo em LICENSE.