agent-auth: authorization for agents

When an agent calls tools for someone, an API key can't say who the user is, which agent is acting, what was allowed or how to take it back. This project answers that with OAuth 2.1, in the shape the MCP spec asks for.

  • OAuth 2.1
  • MCP
  • Security

The flow

The flowAuthorization serverAgentMCP serverAPI1 · 401 + metadata3 · token aud=MCP2 · PKCE + consent4 · token exchange5 · aud=APIrevocation
The agent is the official MCP Python SDK client, with nothing specific to this project. From the 401 on, it discovers the authorization server, registers and asks for consent with PKCE by itself. It also steps up its scope when a tool needs more.
  1. Without a token, the MCP server answers 401 and points to its Protected Resource Metadata (RFC 9728).
  2. The user signs in and approves the request. The screen shows which client is asking, where the code goes back to and which services it will call for the user.
  3. The token lasts 5 minutes and is valid only at that MCP server (RFC 8707). For tools that need more, the server answers 403 insufficient_scope.
  4. The MCP server never forwards the token it got: it exchanges it (RFC 8693) for one with the same or fewer scopes that expires sooner and names the chain in act.
  5. The API sees "MCP ← agent ← Alice" and only accepts user tokens. A machine token with the same scope gets 403.
  6. The user revokes consent: revocation takes down the refresh tokens and every exchanged token. Servers check the revocation list every few seconds and start refusing if it goes stale.

What's inside

  • Authorization server: authorization code with PKCE S256, iss in the response (RFC 9207), refresh rotation with reuse detection
  • Client registration by Client ID Metadata Document (the new default), with an SSRF-safe fetcher, plus throttled Dynamic Client Registration
  • Machine-to-machine with client_credentials and private_key_jwt, no shared secrets
  • ASGI guard for MCP servers and APIs, with per-tool scopes read from the JSON-RPC body
  • Append-only, hash-chained audit log: which agent did what, through which service, for which user
  • One process with SQLite, about 70 MB of RAM

Attacks the tests try

Each protection was broken on purpose, one at a time, to check that some test fails. All 35 breaks were caught.

  • Swapped redirect_uri: look-alike host, other path, fragment, port. An unknown URI gets an error page, never a redirect
  • PKCE missing, plain or wrong. A wrong verifier burns the code
  • A token for another audience, and forged tokens: alg none, another key, HS256 with the public key
  • Scope widened through exchange, refresh or client_credentials
  • Replayed code (revokes what it issued), refresh token (revokes the family) and client assertion
  • Revoked tokens, cascading revocation and a revocation list that goes down
  • Client registration floods, forged X-Forwarded-For, client caps
  • Confused deputy: a look-alike client, a service using a token sent to another service, exchange into an undelegated resource, injected actor_token, a machine token on a user's data
  • CSRF on consent, clickjacking, approving someone else's request
  • CIMD SSRF: private, loopback and link-local IPs, DNS that mixes in a private IP, redirects to cloud metadata

Run it locally

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

Limits

Tokens are bearer, with no DPoP yet, and there is a single signing key with no rotation. The identity provider that ships with it is for development only. No one has audited the code from outside.