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.
The flow
- Without a token, the MCP server answers 401 and points to its Protected Resource Metadata (RFC 9728).
- 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.
- 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.
- 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.
- The API sees "MCP ← agent ← Alice" and only accepts user tokens. A machine token with the same scope gets 403.
- 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.