agent-auth: autorização para agentes

Quando um agente chama ferramentas por alguém, uma chave de API não diz quem é o usuário, qual agente está agindo, o que foi permitido nem como desfazer. Este projeto responde isso com OAuth 2.1 no formato que a spec do MCP pede.

  • OAuth 2.1
  • MCP
  • Security

O fluxo

O fluxoServidor de autorizaçãoAgenteServidor MCPAPI1 · 401 + metadata3 · token aud=MCP2 · PKCE + consentimento4 · troca de token5 · aud=APIrevogação
O agente é o cliente oficial do SDK MCP em Python, sem nada específico deste projeto. A partir do 401, ele sozinho descobre o servidor de autorização, se registra e pede consentimento com PKCE. Também amplia o escopo quando uma ferramenta pede mais.
  1. Sem token, o servidor MCP responde 401 e aponta para o Protected Resource Metadata (RFC 9728).
  2. O usuário entra e aprova o pedido. A tela mostra qual cliente pede, para onde o código volta e quais serviços ele vai chamar em nome do usuário.
  3. O token dura 5 minutos e vale só para aquele servidor MCP (RFC 8707). Para ferramentas que precisam de mais, o servidor responde 403 insufficient_scope.
  4. O servidor MCP não repassa o token que recebeu: ele o troca (RFC 8693) por outro, com escopo igual ou menor, que expira antes e registra a cadeia em act.
  5. A API vê "MCP ← agente ← Alice" e só aceita tokens de usuário. Um token de máquina com o mesmo escopo leva 403.
  6. O usuário revoga o consentimento: a revogação derruba os refresh tokens e todos os tokens trocados. Os servidores consultam a lista de revogados a cada poucos segundos e, se ela ficar velha, passam a recusar.

O que tem dentro

  • Servidor de autorização: authorization code com PKCE S256, iss na resposta (RFC 9207), refresh rotacionado com detecção de reuso
  • Registro de cliente por Client ID Metadata Document (o padrão novo), com fetch protegido contra SSRF, e Dynamic Client Registration com limite
  • Machine-to-machine com client_credentials e private_key_jwt, sem segredo compartilhado
  • Middleware ASGI para MCP e APIs, com escopo por ferramenta lido do JSON-RPC
  • Log de auditoria append-only, encadeado por hash: qual agente fez o quê, por qual serviço, para qual usuário
  • Um processo com SQLite, uns 70 MB de RAM

Ataques que os testes tentam

Cada proteção foi quebrada de propósito, uma por vez, para conferir que algum teste falha. Das 35 quebras, todas foram pegas.

  • redirect_uri trocado: host parecido, outro caminho, fragmento, porta. URI desconhecida vira página de erro, nunca redirect
  • PKCE ausente, plain ou errado. Um verifier errado inutiliza o código
  • Token de outra audiência e tokens forjados: alg none, outra chave, HS256 com a chave pública
  • Escopo ampliado na troca, no refresh ou no client_credentials
  • Replay de código (revoga o que ele emitiu), de refresh token (revoga a família) e de client assertion
  • Token revogado, revogação em cascata e lista de revogados fora do ar
  • Flood de registro de cliente, X-Forwarded-For forjado, limite de clientes
  • Confused deputy: cliente que imita outro, serviço usando token enviado a outro serviço, troca para recurso não delegado, actor_token injetado, token de máquina em dado de usuário
  • CSRF no consentimento, clickjacking, aprovar o pedido de outra pessoa
  • SSRF no CIMD: IP privado, loopback, link-local, DNS que mistura IP privado, redirect para metadata da nuvem

Rodar local

git clone https://github.com/vicgamelo/agent-auth
cd agent-auth && uv sync
uv run agent-auth-demo

Limites

O token é bearer, sem DPoP por enquanto, e há uma chave de assinatura só, sem rotação. O provedor de identidade que acompanha o projeto é de desenvolvimento. Ninguém auditou o código de fora.