Home > Dev Backend > Multitenant Auth API
RESUMO
Projeto Multitenant Auth API
Este é um projeto "end to end" de uma Plataforma de Identidade e Acesso (IAM) multi-tenant construída em Java/Spring Boot, cobrindo autenticação via JWT, autorização baseada em papéis (RBAC), OAuth2 Client Credentials para integrações máquina-a-máquina, autenticação multifator (TOTP), e um conjunto completo de recursos de segurança avançada, testes automatizados, observabilidade e CI/CD.
DETALHAMENTO
Tecnologias Utilizadas:
Linguagem/Runtime: Java 21;
Framework: Spring Boot 3.3.4 (Web, Security, Data JPA, AOP, Validation, Actuator);
Banco de dados: PostgreSQL 16, com migrations via Flyway;
Cache/Sessão: Redis 7 (blacklist de tokens, rate limiting, tentativas de login);
Autenticação: JWT assinado com RS256 (JJWT 0.13.0);
Autorização: RBAC declarativo (@PreAuthorize);
MFA: TOTP (dev.samstevens.totp) com QR Code (ZXing embutido);
Rate Limiting: Bucket4j (token bucket) com backend distribuído no Redis;
Observabilidade: Micrometer + Prometheus (métricas), Logback + Logstash Encoder (logs estruturados em JSON), correlation ID por requisição;
Documentação de API: springdoc-openapi (Swagger UI);
Testes: JUnit 5, Mockito, Testcontainers (Postgres + Redis reais em integração), JaCoCo (cobertura);
Build: Maven (com Maven Wrapper);
Containerização: Docker (build multi-stage) e Docker Compose;
CI/CD: GitHub Actions.
Resultados Obtidos:
10 fases (Épicos) e mais de 30 tarefas (Histórias de Usuários) concluídas de ponta a ponta.
98 testes automatizados (unitários + integração), rodando a cada push via CI.
87% de cobertura de instruções e 80% de cobertura de branches (JaCoCo, relatório combinado unitários + integração).
Conjunto completo de recursos de segurança: autenticação JWT, RBAC, OAuth2 Client Credentials, MFA via TOTP, rate limiting, proteção contra brute force, auditoria de eventos e varredura sistemática de vulnerabilidades comuns (adulteração de token, vazamento de dados, isolamento cross-tenant).
Pipeline de CI/CD funcional, com build e suíte de testes completa validados automaticamente no GitHub Actions.
Imagem Docker multi-stage e Docker Compose permitindo subir a stack inteira com um único comando.
Fluxos de Autenticação e Autorização
Decisões de Arquitetura:
Algumas das decisões mais relevantes tomadas ao longo do projeto, com a motivação por trás de cada uma:
Multi-tenancy por coluna tenant_id (schema único e compartilhado), com isolamento automático via Hibernate Filter interceptado por AOP — simplicidade operacional em troca de isolamento total de schema-per-tenant e prevenção de vazamento inter tenant.
UUID como chave primária em todas as entidades — evita previsibilidade sequencial de IDs e facilita a escalabilidade horizontal.
JWT assinado com RS256, par de chaves RSA gerado em memória a cada inicialização — elimina a necessidade de gerenciar um segredo simétrico compartilhado, ao custo de invalidar sessões ativas a cada restart (uma simplificação deliberada e documentada, aceitável para um projeto de portfólio).
Tenant identificado a partir do JWT, não mais do header, após a autenticação — impede que o cliente manipule o tenant de uma requisição autenticada trocando um header.
Blacklist de tokens via Redis com TTL igual ao tempo restante do token — logout efetivo sem precisar armazenar nem consultar todos os tokens já emitidos.
RBAC com papéis fixos (ADMIN, MEMBER) e permissões granulares — simples de implementar, com checagem declarativa via @PreAuthorize.
Clientes OAuth2 escopados por tenant — cada tenant gerencia suas próprias integrações máquina-a-máquina, sem um conceito de "cliente global".
Segredo do MFA criptografado em repouso (AES-256/GCM) — nunca armazenado em texto puro, mesmo precisando ser decifrado a cada verificação de código. Pequena porcentágem do processamento sacrificada em nome da segurança.
Rate limiting com token bucket (Bucket4j + Redis) — permite rajadas curtas controladas, com estado compartilhado entre múltiplas instâncias da aplicação.
Auditoria de segurança e métricas conectadas num único ponto de integração (SecurityAuditService) — todo evento já auditado (login, MFA, criação de cliente OAuth2, etc.) automaticamente também vira uma métrica Prometheus, sem duplicar código em cada Service.
Imagens da Documentação da API (Swagger)
Problemas Enfrentados:
Uma seleção dos desafios e investigações mais relevantes ao longo do desenvolvimento:
LazyInitializationException em coleções do Hibernate carregadas fora de uma sessão ativa — apareceu tanto no filtro de isolamento por tenant (Fase 1) quanto em testes de segurança criados depois (Fase 8). Resolvido garantindo que o código que acessa coleções lazy sempre rode dentro de uma transação ativa (@Transactional).
Conflito entre múltiplas definições do mesmo filtro Hibernate (@FilterDef) — ao adicionar uma nova entidade multi-tenant (OAuthClient), copiar o padrão de outra entidade duplicou a definição do filtro, que precisa existir uma única vez por unidade de persistência; entidades adicionais só precisam de @Filter para usar a definição já existente.
Incompatibilidade de versão entre o springdoc-openapi e o Spring Framework — uma versão recente do springdoc esperava encontrar uma classe (LiteWebJarsResourceResolver) que só existe a partir do Spring Framework 6.2, enquanto o Spring Boot 3.3.4 usado no projeto traz a versão 6.1.x. Diagnosticado analisando a árvore de dependências e o histórico de mudanças do Spring Framework, e resolvido fixando uma versão do springdoc testada especificamente contra essa linha do Boot.
@SpringBootTest desativa observabilidade por padrão — um teste de métricas falhava consistentemente só dentro da suíte de testes, nunca ao rodar a aplicação normalmente. A causa era um comportamento pouco divulgado do próprio Spring Boot Test, que desliga a exportação de métricas para evitar chamadas acidentais a um backend real durante testes — corrigido com @AutoConfigureObservability no teste específico que precisava validar isso.
Rejeição silenciosa de um endpoint do Actuator — o endpoint do Prometheus não aparecia, sem nenhum erro explícito. Isolado usando o relatório de avaliação de condições do próprio Spring Boot (flag --debug), que mostra exatamente qual pré-condição de auto-configuração não foi satisfeita.
Product Backlog:
(Épicos e Histórias de Usuário já traduzidas para liguágem técnica)
Fase 0 — Fundamentos e Setup
0.1 - Setup inicial do repositório e projeto Maven (Java 21, estrutura de pacotes, Maven Wrapper)
0.2 - Docker Compose com PostgreSQL e Redis para desenvolvimento local
0.3 - Perfis de ambiente (dev, test) via application-*.yml
0.4 - Setup base de testes com JUnit 5 e Testcontainers
Fase 1 — Multi-tenancy e Modelagem Base
1.1 - Modelagem da entidade Tenant
1.2 - Modelagem da entidade User, vinculada ao tenant via tenant_id
1.3 - Filtro automático de isolamento por tenant, via Hibernate Filter interceptado por Spring AOP
Fase 2 — Identidade e Cadastro de Usuários
2.1 - CRUD de usuários (criação, listagem, consulta por ID)
2.2 - Hashing de senha com BCrypt
2.3 - Validações de entrada com Bean Validation
Fase 3 — Autenticação (JWT)
3.1 - Configuração base do Spring Security (stateless, sem sessão)
3.2 - Endpoint de login com emissão de access token e refresh token (RS256)
3.3 - Filtro de validação de token em toda requisição autenticada
Fase 4 — Autorização (RBAC)
4.1 - Modelagem de Role e Permission, com seed de papéis padrão
4.2 - Checagem de acesso por permissão via @PreAuthorize
4.3 - Escopo das regras de autorização isolado por tenant
Fase 5 — Gestão de Sessão e Revogação (Redis)
5.1 - Integração com Redis
5.2 - Blacklist de tokens para logout efetivo
5.3 - Rotação de refresh token (uso único, invalidação do token anterior)
Fase 6 — OAuth2 para Aplicações Clientes
6.1 - Modelagem de clientes OAuth2 (client_id/client_secret), escopados por tenant
6.2 - Fluxo Client Credentials completo, com endpoint administrativo de registro de clientes
Fase 7 — Segurança Avançada
7.1 - Rate limiting por IP (token bucket via Bucket4j + Redis)
7.2 - Proteção contra brute force (bloqueio de conta após tentativas falhas consecutivas)
7.3 - Auditoria de eventos de segurança (login, logout, refresh, MFA, criação de clientes OAuth2)
7.4 - Autenticação multifator (MFA) via TOTP, com QR Code e segredo criptografado em repouso
Fase 8 — Testes
8.1 - Testes unitários (JUnit + Mockito)
8.2 - Testes de integração com Testcontainers (Postgres e Redis reais)
8.3 - Varredura de segurança sistemática (adulteração de JWT, isolamento cross-tenant, vazamento de dados sensíveis, headers de segurança)
Fase 9 — Observabilidade e Documentação
9.1 - Logs estruturados em JSON, com correlation ID propagado por requisição
9.2 - Métricas via Spring Boot Actuator e Prometheus, incluindo métricas de negócio conectadas à auditoria de segurança
9.3 - Documentação interativa da API via OpenAPI/Swagger
Fase 10 — Finalização
10.1 - Pipeline de CI via GitHub Actions (build, testes e cobertura a cada push)
10.2 - Imagem Docker multi-stage (build enxuto, usuário não-root) e Docker Compose completo
10.3 - Este README
10.4 - Guia de deploy documentado — veja DEPLOY.md
Imagens dos testes manuais da API (Postman)
Melhorias Futuras / Próximos Passos:
Algumas melhorias ou mudanças que podem ser implementadas no futuro e que por alguma limitação de tempo ou de escopo não foram incluídas durante o projeto:
Códigos de recuperação (recovery codes) para o MFA, cobrindo o cenário de perda do dispositivo autenticador.
Endpoint de troca de senha para o usuário autenticado.
Rate limiting por tenant, além do atual por IP.
Tracing distribuído (ex: OpenTelemetry) complementando as métricas e logs já existentes.
Testes de carga (ex: k6 ou Gatling) para validar o comportamento sob volume real de requisições.
Deploy real e público, mantido no ar (hoje documentado apenas como guia, sem instância ativa — ver DEPLOY.md) no repositório do projeto no Github.
Internacionalização das mensagens de erro (hoje apenas em português).
Ambiente de desenvolvimento:
Debian Linux 13
Visual Studio Code
Docker + Docker Compose
Github
Para ter acesso ao código fonte e a documentação completa, acesse o perfil do projeto no Github.