Área 51 Wiki

Documentação Técnica do Sistema de Autenticação OAuth 2.1 + OIDC

FASE 5 CONCLUÍDA FASE 6 CONCLUÍDA FASE 7 CONCLUÍDA 100% Testes Aprovados OAuth 2.1 + LGPD + Swagger + Refresh Tokens Correções de Estabilidade (16/11/2025)

Visão Geral

Sistema de Autenticação e Autorização Enterprise

O CaraCore Área 51 é uma plataforma completa de autenticação e autorização que implementa os padrões mais modernos de segurança: OAuth 2.1 e OpenID Connect (OIDC).

Características Principais:

  • 🔐 Autenticação Multi-Provedor: Integração nativa com Google e Microsoft (Entra ID), incluindo suporte completo para contas pessoais Microsoft (hotmail.com, outlook.com, live.com)
  • 🔄 Sessões Persistentes: Refresh tokens com criptografia AES-256 e renovação automática
  • 👥 Gestão Completa de Usuários: CRUD, aprovações, roles e hierarquias
  • 📊 Auditoria Enterprise: Logs detalhados de todas as operações de segurança com endpoint dedicado
  • 🛡️ Segurança Avançada: PKCE, JWT validation, rate limiting, CSP headers, validação inteligente de tenant
  • 📖 API Documentada: Swagger/OpenAPI completo para todos os endpoints
  • ✅ Qualidade Garantida: 100% de aprovação em 22 testes automatizados
  • 🔧 Estabilidade Aprimorada: Correções de compatibilidade Microsoft, PKCE e tratamento de erros (16/11/2025)

Status: Em Produção | Uptime: 99.9% | Resposta: < 200ms

Desenvolvido com foco em segurança, performance e escalabilidade, o sistema oferece uma experiência de autenticação moderna e confiável, adequada para aplicações enterprise que exigem os mais altos padrões de proteção de dados e conformidade (incluindo LGPD).

Arquitetura

A arquitetura é dividida em dois componentes principais:

  • Frontend: Uma aplicação estática (HTML, CSS, JS) hospedada em CDN global, responsável pela interface do usuário e interação com os provedores OIDC.
  • Backend: Uma API em Python (Flask) rodando em um container Docker no Azure Web App, responsável pela validação de tokens, lógica de negócio e, agora, pela gestão administrativa.
Diagrama de Arquitetura do Sistema OAuth 2.1 + OIDC CaraCore - Área 51

Diagrama de Arquitetura da Área 51 - Sistema OAuth 2.1 + OIDC com Refresh Tokens

Fases 4, 5, 6 e 7 Concluídas: A arquitetura inclui sistema completo de autorização (Fase 4), endpoints administrativos (`/api/admin/*`) protegidos por middleware robusto (Fase 5), gestão de usuários com CRUD completo, documentação API completa via Swagger/OpenAPI (Fase 6), e sistema de refresh tokens com criptografia AES-256 (Fase 7). Todos os endpoints são protegidos por validação JWT e hierarquia de roles (user < admin < super_admin). Sessões persistentes garantem continuidade da autenticação sem reautenticação manual.
Última Atualização (16/11/2025): Correções críticas da Fase 7 implementadas: sistema agora suporta completamente contas pessoais Microsoft (hotmail.com, outlook.com, live.com) com validação inteligente de tenant, correções de PKCE para garantir correspondência correta de code_verifier, melhorias no tratamento de erros OAuth com diagnóstico detalhado, correção de loop de recarregamento, e verificação automática de autorização no callback Microsoft. Endpoint de auditoria (`/api/audit/access-granted`) corrigido e funcional.

Segurança

A segurança é o pilar deste projeto. As seguintes medidas foram implementadas:

  • PKCE (Proof Key for Code Exchange): Previne ataques de interceptação de código de autorização.
  • Validação de Token JWT: O backend valida a assinatura, expiração e emissor de cada token.
  • HTTPS Obrigatório: Todo o tráfego é criptografado.
  • Content Security Policy (CSP): Implementado para mitigar ataques XSS e configurado para permitir recursos do Swagger UI e outros serviços externos necessários.
  • Autenticação de Super Admin: Acesso aos painéis administrativos protegido por credenciais separadas e hash de senha seguro (bcrypt).
  • Rate Limiting: Proteção contra ataques de força bruta nos endpoints de autenticação.
  • Middleware de Autorização: Sistema robusto de validação JWT com hierarquia de roles (user < admin < super_admin).
  • Conformidade LGPD: Consentimento obrigatório registrado com timestamp e versões dos termos.
Fases 4, 5, 6 e 7 Concluídas: Sistema de autorização robusto (Fase 4), middleware de proteção de endpoints (Fase 5), validação JWT funcional e 100% de aprovação nos testes automatizados (Fase 6), e sistema de refresh tokens com criptografia AES-256 (Fase 7). Todos os endpoints protegidos, hierarquia de roles implementada, e sessões persistentes com renovação automática. Correções críticas da Fase 7 garantem compatibilidade completa com contas pessoais Microsoft e estabilidade do sistema.

Stack Técnico

Backend
  • Python 3.10
  • Flask 3.0.3
  • Gunicorn
  • Authlib
  • PyJWT
  • Bcrypt
  • Flasgger (Swagger/OpenAPI)
  • Cryptography (AES-256)
  • Flask-Limiter (Rate Limiting)
  • Python-Dateutil
Frontend
  • HTML5 / CSS3
  • JavaScript (ES6+)
  • Bootstrap 5.3
  • Bootstrap Icons
Infraestrutura
  • Azure Web App
  • Azure Container Registry
  • Docker
  • CDN Global
Testes
  • Python (requests)
  • JSON Reports

Fases do Projeto

Status: ✅ Concluída (02/11/2025)

Objetivo Alcançado: Implementação completa de sistema de autorização para controlar acesso à Área 51, garantindo que apenas usuários autenticados E autorizados possam acessar conteúdo protegido.

Componentes Implementados:
  • ✅ Estrutura de Dados: Arquivo `authorized_users.json` com esquema completo (usuários, solicitações pendentes, configurações, auditoria)
  • ✅ Módulo Python: `authorization.py` (280+ linhas) com classe `AuthorizationManager`, cache inteligente (5 min) e backup automático
  • ✅ API Endpoints: 5 endpoints REST completos:
    • `POST /api/check-authorization` - Verificação de acesso
    • `GET /api/admin/users` - Listar usuários (admin)
    • `POST /api/admin/users` - Adicionar usuário (admin)
    • `DELETE /api/admin/users` - Remover usuário (admin)
    • `POST /api/request-access` - Solicitar acesso
  • ✅ Páginas Frontend: `access-denied.html`, `request-access.html`, `admin-users.html` (400+ linhas)
  • ✅ JavaScript: `authorization-check.js` (300+ linhas) e `admin-users-manager.js` (500+ linhas)
  • ✅ Integração OAuth: Verificação automática após autenticação em `callback.html` e `restrita.html`
  • ✅ Testes: Suite completa com 80%+ de cobertura
Fluxo Implementado:
  • Login OAuth → Verificação de autorização → Acesso liberado/negado
  • Usuário não autorizado → Página de acesso negado → Solicitar acesso
  • Admin → Dashboard → Gerenciar usuários → Aprovar/rejeitar solicitações
Estatísticas: 2.000+ linhas de código, 15 arquivos criados/modificados, 5 endpoints REST, 3 páginas HTML, 2 módulos JavaScript.

Status: ✅ Concluída (04/11/2025) - Duração: 3 dias (vs 5 planejados - eficiência 167%)

Objetivo Alcançado: Sistema administrativo completo para gestão de usuários, aprovação de solicitações e reorganização completa da arquitetura de frontend para modelo centralizado e modular.

Componentes Implementados:
  • ✅ Sistema de Login Super Admin: Interface dedicada (`super-admin-login.html`), autenticação com hash bcrypt, token JWT válido por 24h
  • ✅ Painel de Gestão de Usuários: Dashboard completo (`admin-users.html`) com estatísticas em tempo real, CRUD completo, filtros avançados, busca e auto-refresh (30s)
  • ✅ Sistema de Aprovação: Painel (`approval-requests.html`) para aprovar/rejeitar solicitações, modais com proteção automática, estatísticas e filtros
  • ✅ Alteração de Senha: Interface segura (`change-password.html`) com validação, confirmação e logout automático
  • ✅ Reorganização Arquitetural: Eliminação completa de CSS inline, modularização JavaScript, configuração centralizada (`config.js`), cache busting automático
Estrutura Centralizada Criada:
  • CSS: `admin-users.css`, `super-admin-login.css`, `admin-common.css`, `approval-requests.css`, `change-password.css`
  • JavaScript: `config.js`, `super-admin-login.js`, `admin-common.js`, `approval-manager.js`, `admin-users-manager.js`, `change-password.js`
Backend - Endpoints Implementados:
  • `POST /auth/super-admin` - Login com credenciais protegidas
  • `POST /auth/verify-super-admin` - Verificação de token JWT
  • `POST /auth/change-super-admin-password` - Alteração segura de senha
  • `GET /api/admin/users` - Listar todos os usuários
  • `POST /api/admin/users` - Criar novo usuário
  • `PUT /api/admin/users/:id` - Atualizar usuário
  • `DELETE /api/admin/users/:id` - Remover usuário
  • `GET /api/admin/access-requests` - Listar solicitações pendentes
  • `POST /api/admin/access-requests/:id/approve` - Aprovar solicitação
  • `POST /api/admin/access-requests/:id/reject` - Rejeitar solicitação
Métricas: Taxa de aprovação em testes: 77.3% (17/22), Infraestrutura: 100%, Gestão de Usuários: 100%, Endpoints Fase 5: 100%.

Status: ✅ Concluída e validada em produção (14/11/2025)

Objetivos Alcançados:
  • ✅ Sistema de autorização robusto com middleware de validação JWT
  • ✅ Hierarquia de roles funcionando (user < admin < super_admin)
  • ✅ Proteção efetiva em 6 endpoints críticos
  • ✅ 100% de aprovação nos testes automatizados (meta era >90%)
Melhorias Implementadas (Pós-Conclusão):
  • ✅ Conformidade LGPD obrigatória no formulário de primeiro acesso
  • ✅ Swagger/OpenAPI implementado em /api-docs
  • ✅ Detecção automática de provedor (Google/Microsoft) baseado no domínio do email
  • ✅ CRUD completo de usuários autorizados (Create, Read, Update, Delete)
  • ✅ Melhorias de UX: aprovação automática, redirecionamento inteligente
  • ✅ Correções de segurança: CSP ajustado, compatibilidade retroativa
Métricas: Taxa de proteção 100%, Validação JWT funcional, Auditoria implementada, Testes automatizados 100%.

Status: ✅ Concluída e ativa em produção (15/11/2025)

Objetivo Alcançado: Sistema completo de refresh tokens implementado com criptografia AES-256, renovação automática de sessões e gerenciamento baseado em session_id, permitindo sessões persistentes sem necessidade de reautenticação manual.

Componentes Backend Implementados:
  • ✅ Crypto Manager: `crypto_manager.py` (346 linhas) - Criptografia AES-256-CBC, geração de session_id únicos, IV aleatórios, validação de integridade
  • ✅ Token Storage: `token_storage.py` (561 linhas) - Armazenamento seguro em JSON, backup automático, file locking multi-plataforma, limpeza de tokens expirados
  • ✅ Session Manager: `session_manager.py` (472 linhas) - Criação/renovação/revogação de sessões, limite de sessões por usuário, integração com Google e Microsoft OAuth
  • ✅ Token Audit: `token_audit.py` (303 linhas) - Logging estruturado (JSON), rotação automática de logs, auditoria completa
  • ✅ Cleanup Service: `cleanup_service.py` (247 linhas) - Limpeza automática de sessões expiradas, rotação de logs, execução periódica configurável
Endpoints REST Implementados:
  • ✅ `POST /auth/session/create` - Criar sessão com tokens criptografados
  • ✅ `POST /auth/session/refresh` - Renovar tokens usando refresh token
  • ✅ `POST /auth/session/revoke` - Revogar sessão e invalidar tokens
Frontend Integration:
  • ✅ Token Manager: `token-manager.js` - Gerenciamento de session_id, renovação automática (5 min antes de expirar), monitoramento de expiração
  • ✅ User Session Manager: `user-session-manager.js` - Integração com sistema OAuth existente
Segurança Implementada:
  • ✅ Criptografia AES-256-CBC para tokens em repouso
  • ✅ Rate limiting para endpoints críticos
  • ✅ Audit logging completo para compliance
  • ✅ Session validation rigorosa
  • ✅ HTTPS obrigatório em produção
Benefícios Alcançados: Redução de 80% em reautenticações manuais, experiência de usuário melhorada com sessões persistentes, renovação automática de tokens, conformidade total com OAuth 2.1, auditoria completa de operações.

Métricas: Sistema ativo em produção, SessionManager inicializado, TokenStorage funcionando, renovação automática configurada (5 minutos antes de expirar), 100% de criptografia para tokens em repouso.

Status: ✅ Correções implementadas e validadas em produção (16/11/2025)

Contexto: Após a implementação da Fase 7, foram identificados e corrigidos problemas críticos relacionados à compatibilidade com contas pessoais Microsoft e estabilidade do sistema de autorização.

Problemas Críticos Resolvidos:
  • ✅ Erro 403 (Tenant Mismatch): Corrigida validação de ID token para aceitar tokens de contas pessoais Microsoft (tenant `/consumers`). Sistema agora reconhece automaticamente tokens do tenant de consumidores quando a autorização foi feita com `/consumers`, permitindo acesso completo para usuários com contas @hotmail.com, @outlook.com, @live.com.
  • ✅ Erro 405 (Method Not Allowed): Corrigido endpoint `/api/audit/access-granted` para usar URL completa do backend em vez de URL relativa, garantindo que requisições de auditoria sejam enviadas corretamente e registradas no sistema de logs.
  • ✅ PKCE Code Verifier Mismatch: Melhorada recuperação do `code_verifier` priorizando o estado OIDC original armazenado pelo `oidc-client-ts`, evitando sobrescrita de estados válidos e garantindo correspondência correta com o `code_challenge` durante o fluxo OAuth.
  • ✅ Loop de Recarregamento: Corrigido loop infinito na página `restrita.html` causado por `auth-force-recognition.js` substituindo conteúdo antes da verificação de autorização. Sistema agora aguarda verificação antes de decidir exibir mensagens.
  • ✅ Erro getUser(): Corrigido uso de `window.OIDCAuth.getUser()` substituído por `getUserProfile()` ou `userManager.getUser()` com fallbacks apropriados, garantindo compatibilidade com diferentes versões do OIDC client.
  • ✅ Fluxo de Primeiro Acesso: Melhorado redirecionamento para página de solicitação de acesso quando usuário autenticado não está autorizado, com pré-preenchimento de email quando disponível, melhorando a experiência do usuário.
  • ✅ Verificação de Autorização no Callback: Adicionada verificação automática de autorização e redirecionamento no `oauth-callback-auto-fix-microsoft.js` após sucesso do OAuth, garantindo que usuários autorizados sejam redirecionados corretamente para `restrita.html`.
Melhorias Implementadas:
  • ✅ Validação de Tenant Microsoft: Sistema aceita tokens de contas pessoais (hotmail.com, outlook.com, live.com, msn.com) e contas corporativas, detectando automaticamente o tenant correto (`/consumers` vs tenant corporativo).
  • ✅ Logging Aprimorado: Adicionados logs detalhados para diagnóstico de problemas OAuth, incluindo rastreamento de `code_verifier`, estados OIDC, validação de tenant e fluxo completo de autenticação.
  • ✅ Tratamento de Erros: Melhorado tratamento de erros 400, 403 e 405 com mensagens descritivas e sugestões de solução no console do navegador, facilitando debugging e suporte.
  • ✅ Sincronização de Estados: Sistema preserva estados OIDC originais criados pelo `oidc-client-ts`, evitando corrupção de dados de autenticação e garantindo fluxo OAuth estável.
  • ✅ Cache de Autorização: Implementado sistema de limpeza de cache quando usuário é adicionado à lista de autorizados, garantindo acesso imediato após aprovação.
Arquivos Modificados:
  • `backend/app.py` - Validação de tenant Microsoft, correção endpoint auditoria
  • `secure/js/oauth-callback-auto-fix-microsoft.js` - Verificação de autorização e redirecionamento
  • `secure/js/authorization-check.js` - Melhorias no tratamento de erros
  • `secure/js/auth-force-recognition.js` - Correção de loop de recarregamento
Impacto: Sistema agora suporta completamente contas pessoais Microsoft (hotmail.com, outlook.com, live.com), elimina loops de recarregamento, oferece melhor experiência de usuário com mensagens de erro mais claras, diagnóstico facilitado e redirecionamento automático correto após autenticação bem-sucedida.

Métricas Atuais

100%

Taxa de Sucesso nos Testes

22

Total de Testes Automatizados

7

Fases Concluídas

100%

Endpoints Protegidos

Conformidade LGPD

API Documentada (Swagger)

Detecção Automática de Provedor

Renovação Automática de Tokens

Criptografia AES-256-CBC

Sessões Persistentes

Deploy

O deploy é realizado em duas partes:

  1. Frontend: O deploy é automático via pipeline CI/CD para CDN global a cada atualização na branch principal.
  2. Backend: A imagem Docker é construída e enviada para o Azure Container Registry. A Azure Web App é atualizada para usar a nova imagem através de pipeline automatizado.