Deployment Topologies

AuthPlane supports ten deployment shapes. Each upstream topology page is self-contained: a component diagram, a wire-level sequence diagram, an operator playbook in three configuration modes, and a peek at what authserver does behind the curtain. This page summarizes each shape and when to pick it.

The decision hinges on one question: where do your MCP servers get their tokens from?

AuthPlane mints them → single MCP, direct fan-out, MCP gateway (Mint), or folded resource.
An external OAuth provider mints them (GitHub, Google, Slack, …) → broker MCP, MCP gateway (Broker), or client-credentials hop.
Identity comes from an upstream IdP, or there’s no user at all → OIDC federated login, enterprise XAA, or M2M client credentials.

AuthPlane mints the tokens

Single MCP (`single-mcp`)

One agent, one Mint resource, one user — authorization code + PKCE. The canonical baseline; pick it first when in doubt. Everything else in this catalog is a variation on this shape. Read the full topology →

Direct fan-out (`direct-fanout`)

One agent calls many independent MCP servers, with per-MCP user consent. Choose it when multiple unrelated MCP servers all need user authorization and you don’t want (or need) a gateway between agent and servers. Read the full topology →

Folded resource (`folded-resource`)

Multiple internal services hidden behind one resource with a richer scope catalog. The “hidden” services become implementation details of the gateway and are never named at the authorization server — total encapsulation, per-user audit. Choose it when internal services share audit/ownership and don’t warrant separate registrations. Read the full topology →

MCP gateway — Mint (`mcp-gateway-mint`)

A gateway fronts a hidden Mint resource via a fronting link, with the delegation chain visible on the wire. Choose it when you want full encapsulation of the backend and per-user audit through the act-claim chain. Read the full topology →

An external provider mints the tokens

Broker MCP (`broker-mcp`)

The agent talks directly to a Broker resource — AuthPlane vends a fresh upstream bearer token per request from the Token Vault. The agent never sees the upstream credentials; the upstream API never sees AuthPlane. Choose it when the agent legitimately needs to reach the provider and there’s no gateway in the way. Read the full topology →

MCP gateway — Broker (`mcp-gateway-broker`)

A gateway fronts an upstream-IdP-backed service; AuthPlane vends the upstream bearer to the gateway, and the delegation chain lives in AuthPlane’s audit only (the upstream token can’t carry it). Choose it when the hidden resource is a Broker and you want the agent fully insulated from the provider. Read the full topology →

Client-credentials hop (`client-credentials-hop`)

A gateway calls hidden infrastructure as itself, deliberately dropping user context at the boundary. Choose it when the hidden API is unrelated infrastructure and per-user audit doesn’t matter for that hop. Read the full topology →

Identity from an upstream IdP — or no user at all

OIDC federated login (`oidc-federated-login`)

Users sign in via their corporate IdP (Okta, Google, Entra). Choose it when you want SSO and you don’t want AuthPlane storing passwords. Read the full topology →

Enterprise XAA (`enterprise-xaa`)

The corporate IdP signs an assertion (ID-JAG) declaring “this agent acts for this user under this policy” — the XAA pattern. The agent presents it to authserver via the RFC 7523 JWT-Bearer grant; AuthPlane verifies the signature against the IdP’s JWKS, applies a policy-engine subject mapping, and issues a normal access token. Choose it when compliance requires the agent-identity trust anchor to be the corporate IdP. Read the full topology →

M2M client credentials (`m2m-client-credentials`)

A backend service authenticates as itself — no user in the loop. Choose it for cron jobs, batch ETL, and internal microservices. Read the full topology →

Combining topologies

These shapes compose, and real deployments commonly stack several:

OIDC-federated login + agent + multiple MCPs — users sign in via Okta, then each agent independently fans out to MCP servers A, B, C with per-MCP consent.
Gateway → Broker in front of Google Calendar + gateway → hidden Mint in front of an internal scheduler — one gateway serves both fronted patterns to different downstream resources.
Enterprise XAA + gateway → hidden Mint — corporate-IdP-signed agent identity flows through the act-claim chain to an internal API.

When in doubt, model each hop as its own topology and stack them.

Three equivalent configuration modes

Every topology can be configured three ways — pick one and stay in it for the whole walkthrough; all three end with the same authserver-side state.

Mode	Where	Best for
Admin UI	`http://localhost:9001` (React SPA embedded in the `authserver` binary)	Exploring, one-off setup, visual confirmation
CLI	`authserver admin <subcommand>`	Local development, scripting, single-host operators
REST API	`POST /admin/...` against `:9001`	CI/CD pipelines, infrastructure-as-code, multi-environment provisioning

All three authenticate with the same admin API key from the AUTHPLANE_ADMIN_API_KEY env var (or YAML admin.api_key). The Admin UI prompts for it on first load and keeps it in sessionStorage; the CLI and REST API read it from the environment. One caveat: federation provider config and the XAA issuer policy are YAML-only at v0.1.x — the affected topology pages call this out in their Configure sections.

Where to go next

Resources & Scopes The vocabulary every topology page assumes.

Token Vault: Mint vs Broker The two backend kinds these topologies are built from.

Delegation & Agent Chains How the act-claim chain threads through gateway topologies.

Topologies index on GitHub The decision tree, notation guide, and all ten full topology pages.

Deployment Topologies

AuthPlane mints the tokens

Single MCP (single-mcp)

Direct fan-out (direct-fanout)

Folded resource (folded-resource)

MCP gateway — Mint (mcp-gateway-mint)