JWT Authentication - Resumo Executivo¶
🎯 Objetivo¶
Permitir que usuários autenticados no site da iFriend utilizem o agente de chat com suas próprias credenciais, eliminando a necessidade de reautenticação e garantindo que as operações sejam executadas no contexto correto do usuário.
📊 Situação Atual vs. Situação Desejada¶
❌ Situação Atual¶
Usuário autenticado no site → Abre chat → Pede para fazer reserva
↓
Agente autentica com credenciais DEFAULT
↓
API retorna dados do usuário DEFAULT
↓
❌ Contexto errado!
Problemas: - Agente não sabe quem é o usuário real - Operações executadas com credenciais genéricas - Impossível fazer ações personalizadas (ver minhas reservas, meu perfil, etc.) - Experiência do usuário quebrada
✅ Situação Desejada¶
Usuário autenticado no site → Abre chat (envia JWT) → Pede para fazer reserva
↓
Agente usa JWT token do usuário
↓
API retorna dados do USUÁRIO REAL
↓
✅ Contexto correto!
Benefícios: - Agente sabe quem está conversando - Operações executadas com credenciais do usuário real - Experiência personalizada (histórico, preferências, etc.) - Segurança: cada usuário opera apenas seus dados
🏗️ Arquitetura em 4 Passos¶
┌─────────────────────────────────────────────────────────────────┐
│ 1. RECEBER JWT │
│ ├─ WebChat: JWT no header/body da requisição │
│ ├─ SSE: JWT no header do POST inicial │
│ ├─ WhatsApp: Lookup em cache (usuário autentica via web) │
│ └─ Slack: Lookup em cache (comando /auth) │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. VALIDAR & DECODIFICAR JWT │
│ ├─ Verifica assinatura │
│ ├─ Verifica expiração │
│ └─ Extrai claims (user_id, email, roles, etc.) │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. INJETAR NO CONTEXTO DA SESSÃO ADK │
│ ├─ Armazena JWT e claims na sessão │
│ ├─ Mantém durante toda a conversa │
│ └─ Disponível para todas as ferramentas │
└────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. USAR JWT NAS FERRAMENTAS │
│ ├─ Ferramentas verificam se há JWT no contexto │
│ ├─ Se SIM → usa JWT do usuário │
│ └─ Se NÃO → usa credenciais default (backward compatible) │
└─────────────────────────────────────────────────────────────────┘
📦 Componentes Principais¶
| Componente | Arquivo | Responsabilidade |
|---|---|---|
| JWT Context Manager | ifriend_agent/session/jwt_context.py |
Decodificar e validar JWT tokens |
| Session Context Extension | ifriend_agent/session/session_context.py |
Armazenar JWT no contexto da sessão ADK |
| Enhanced Auth Manager | ifriend_agent/tools/booking/auth.py |
Usar JWT do contexto quando disponível |
| Adapter Extensions | messaging/adapters/*.py |
Extrair JWT das requisições de cada plataforma |
| Processor Enhancement | messaging/processor.py |
Integrar JWT no fluxo de processamento |
⚙️ Plataformas Suportadas¶
| Plataforma | Método de Envio JWT | Status |
|---|---|---|
| WebChat | Header Authorization: Bearer <token> |
✅ Direto |
| WebChat | Campo jwt_token no body |
✅ Direto |
| SSE | Header Authorization: Bearer <token> |
✅ Direto |
| Autenticação prévia via web → lookup | ⚠️ Requer setup inicial | |
| Slack | Comando /auth <token> → lookup |
⚠️ Requer setup inicial |
📋 Checklist de Implementação (Simplificado)¶
Fase 1: Base (1 semana)¶
- [ ] Criar
JWTContextManagerpara validar tokens - [ ] Estender sessão ADK para armazenar JWT context
- [ ] Modificar
get_auth_headers()para usar JWT do contexto - [ ] Testes unitários dos componentes base
Fase 2: WebChat (3 dias)¶
- [ ] Modificar
WebChatAdapterpara extrair JWT - [ ] Modificar
ConversationProcessorpara injetar JWT context - [ ] Modificar ferramentas de booking para usar JWT context
- [ ] Testes end-to-end WebChat
Fase 3: SSE (2 dias)¶
- [ ] Modificar
SSEAdapterpara extrair JWT - [ ] Testes end-to-end SSE
Fase 4: WhatsApp + Slack (1 semana)¶
- [ ] Criar endpoint
/whatsapp/linkpara vincular conta - [ ] Criar serviço de lookup JWT para WhatsApp
- [ ] Modificar
WhatsAppAdapterpara lookup JWT - [ ] Criar comando Slack
/ifriend-auth - [ ] Modificar
SlackAdapterpara lookup JWT - [ ] Testes WhatsApp e Slack
Fase 5: Finalização (2 dias)¶
- [ ] Documentação completa
- [ ] Exemplos de integração para frontend
- [ ] Deploy e monitoramento
Estimativa Total: 2-3 semanas
💰 Valor de Negócio¶
Para Usuários¶
- ✅ Sem reautenticação: já logou no site? Pode usar o chat direto
- ✅ Experiência personalizada: agente conhece seu histórico, preferências
- ✅ Operações diretas: "ver minhas reservas", "atualizar meu perfil"
- ✅ Segurança: seus dados ficam protegidos, não mistura com outros usuários
Para o Negócio¶
- ✅ Conversão: menos fricção = mais conversões
- ✅ Engagement: experiência personalizada aumenta uso
- ✅ Segurança: compliance com proteção de dados
- ✅ Escalabilidade: suporta multi-tenancy e diferentes roles/permissões
🔐 Segurança¶
Validações Implementadas¶
- ✅ Verificação de assinatura JWT (evita tokens falsificados)
- ✅ Verificação de expiração (tokens expirados são rejeitados)
- ✅ Logs de auditoria (rastreabilidade de quem fez o quê)
- ✅ Fallback seguro (se JWT inválido, usa auth default)
Boas Práticas¶
- 🔒 Tokens nunca são logados completos (apenas parciais)
- 🔒 HTTPS obrigatório para todas as comunicações
- 🔒 Tokens têm tempo de vida limitado (24h padrão)
- 🔒 Suporte a blacklist de tokens revogados (futuro)
📈 Métricas de Sucesso¶
| Métrica | Objetivo | Como Medir |
|---|---|---|
| Adoção JWT | >80% das conversas com JWT | Contador de mensagens com/sem JWT |
| Taxa de Erro JWT | <1% de JWTs inválidos | Log de tokens rejeitados |
| Conversão | +20% nas reservas via chat | Analytics de reservas |
| Performance | <50ms overhead de JWT | Tempo de decodificação/validação |
| Backward Compatibility | 100% das conversas sem JWT funcionam | Testes de regressão |
🚀 Rollout Plan¶
Fase 1: Beta (2 semanas)¶
- Deploy em ambiente de staging
- Teste com usuários beta (10-20 usuários)
- Monitoramento intensivo
- Ajustes baseados em feedback
Fase 2: Produção Gradual (1 semana)¶
- Deploy em produção com feature flag
- Habilitar para 10% dos usuários
- Monitorar métricas
- Aumentar para 50% se OK
- Aumentar para 100% se OK
Fase 3: Otimização (ongoing)¶
- Análise de performance
- Melhorias baseadas em dados
- Novas features (refresh token, SSO, etc.)
❓ FAQ¶
Q: O que acontece se o JWT expirar durante a conversa?¶
A: O agente continua funcionando, mas volta a usar autenticação default. Idealmente, o frontend deve renovar o token antes de expirar.
Q: Funciona para usuários não logados?¶
A: Sim! Se não houver JWT, o sistema usa autenticação default (comportamento atual).
Q: WhatsApp e Slack precisam de auth toda vez?¶
A: Não. Autenticação é one-time. Depois disso, o JWT fica em cache por 30 dias.
Q: Como funciona com múltiplos dispositivos?¶
A: Cada dispositivo tem seu próprio JWT. Sessões são separadas por session_id.
Q: Posso revogar um JWT?¶
A: Sim, implementando blacklist no Redis. Token é verificado contra blacklist antes de usar.
📞 Próximos Passos¶
- Aprovação: Revisar plano com time técnico e stakeholders
- Refinamento: Ajustar prioridades e escopo se necessário
- Sprint Planning: Quebrar em tasks no Jira/Github
- Kick-off: Iniciar implementação Fase 1
📚 Documentação Completa¶
Status: 📋 PLANEJAMENTO COMPLETO
Próximo milestone: Aprovação para iniciar implementação
Estimativa: 2-3 semanas de desenvolvimento
Risco: Baixo (arquitetura modular, backward compatible)
Última atualização: 13 de fevereiro de 2026
Responsável: Tech Lead iFriend Agents
Revisores: DevOps, Security, Product