Skip to main content

OAuth Guard

A tool call has two legs to secure: the inbound connection an AI agent opens to the gateway, and the outbound call Zilla itself makes to an upstream MCP server or HTTP API on the agent's behalf. Three flows cover both:

  • JWT Bearer authenticates the inbound agent connection, at the gateway itself, before any tool call reaches an upstream. It uses the open-source jwt guard.
  • Client Credentials authenticates Zilla's own outbound call to an upstream that expects a service account, independent of whatever credential the agent presented.
  • Token Exchange swaps the agent's inbound token for a different, upstream-scoped token before Zilla calls the upstream.

How It's Wired

JWT Bearer authenticates the inbound session directly on the mcp server binding, through its own options.authorization field, not on a fronting http server route. The jwt guard's extracted credentials are matched against the inbound Authorization header using a template (Bearer {credentials} by default); a request whose header doesn't match, or whose credentials the guard rejects, is turned away with a 401 response and a WWW-Authenticate challenge before it ever reaches the MCP proxy or an upstream tool provider. See JWT Bearer for a worked example.

Client Credentials and Token Exchange authenticate the outbound side instead: the same options.authorization field, but on the mcp client or mcp-http binding that actually reaches the upstream, and naming an oauth guard rather than jwt. The agent's inbound credential and the credential Zilla presents to an upstream are independent — nothing requires them to share a shape, or even a guard type. See Client Credentials and Token Exchange for both.

A second, more granular layer sits on top of session authentication: routes[].guarded on the mcp proxy and mcp client bindings authorizes individual tools, prompts, and resources by role, once the session itself is already authenticated. See Centralized Auth for how these layers combine.

Auth state, JWKS keys for JWT Bearer and cached tokens for Client Credentials and Token Exchange, is held in a store: in-memory for a single instance, or shared via Redis or Hazelcast so every replica in a horizontally scaled deployment sees the same state instead of re-authenticating independently.

Editions

JWT Bearer is fully open source: it reuses the OSS jwt guard. Client Credentials and Token Exchange use the oauth guard, which requires Zilla Plus.