Choose your topology

TL;DR — Every AuthPlane deployment reduces to one of ten canonical topologies. Pick the shape that matches yours by answering three questions: how many MCP servers, who authenticates the user, and does the MCP server need upstream tokens (GitHub, Slack, Google, …). Each topology has a dedicated page with a component diagram, wire-level flow, and end-to-end configuration.

The three questions

Answer these first — they narrow you to one row of the tables below.

  1. How many MCP servers is one agent talking to?
    • One → single-resource.
    • Many → multi-resource (fanout, gateway, folded).
  2. Who authenticates the user?
  3. Does the MCP server need to act on the user’s behalf against a third-party API (call the user’s GitHub, read their Google Calendar)?
    • Yes → broker flavor of whichever shape you picked. AuthPlane vaults the refresh token and vends short-lived access tokens on demand.
    • No → mint flavor (AuthPlane signs its own JWTs for the MCP server, no upstream involvement).

Single-resource topologies

TopologyUse caseDeep-dive
Agent + single MCPOne agent, one MCP server, one user — the canonical baseline.single-mcp
Agent + brokered MCPAgent reaches a service backed by an upstream IdP (Google Calendar, GitHub, Slack, Linear). AuthPlane stores the refresh token and vends short-lived access tokens on demand.broker-mcp
Backend service + MCP (no user)Machine-to-machine — a worker, CI pipeline, or monitoring service acts as itself with a client_credentials grant. No consent, no browser.m2m-client-credentials

Multi-resource topologies

TopologyUse caseDeep-dive
Direct fanoutOne agent talks to multiple MCPs; the user consents at each MCP separately. Simplest, no infra.direct-fanout
Folded resourceMultiple internal services hidden behind one MCP boundary. AuthPlane sees one resource; the MCP fans out privately.folded-resource
Client-credentials hopA gateway calls hidden infra as itself, dropping user context after the first hop. Second hop is M2M.client-credentials-hop
MCP gateway → hidden MintGateway fronts a hidden MCP; AuthPlane issues JWTs to the gateway that carry an act-claim chain naming the downstream.mcp-gateway-mint
MCP gateway → brokerGateway fronts an upstream-IdP-backed service; AuthPlane vends the upstream bearer via the gateway.mcp-gateway-broker

Identity federation topologies

These stack on top of any of the above — they change how the user authenticates, not the token path.

TopologyUse caseDeep-dive
OIDC-federated user loginUsers sign in via Google Workspace, Okta, Entra ID, or any OIDC provider. AuthPlane never sees credentials; it still issues the MCP tokens.oidc-federated-login
Enterprise-Asserted Agent Identity (XAA)Your corporate IdP signs a JWT asserting the agent’s identity. AuthPlane accepts it via JWT Bearer grant (RFC 7523) and mints an MCP token. Skips per-user consent for policy-approved agents.enterprise-xaa

Composing topologies

Real deployments stack shapes. Common combos:

  • OIDC-federated login + direct fanout — users sign in via Okta once, then each agent fans out to MCPs A, B, C with per-MCP consent.
  • MCP gateway → broker (Google Calendar) + MCP gateway → mint (internal scheduling API) — one gateway serves both fronted patterns to different downstream resources.
  • Enterprise XAA + MCP gateway → hidden Mint — corporate-IdP-signed agent identity flows through the act-claim chain into an internal API.

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

What’s on the roadmap

Not yet shipped — co-authorization at first /authorize: a single consent screen for multiple resources via repeated resource= parameters (RFC 8707 multi-resource authorization). Until it lands, use direct fanout (sequential consent) or the gateway pattern (single consent).

Three ways to configure any topology

Every topology page shows the same setup in three parallel modes — pick one, stay in it:

ModeWhereBest for
Admin UIhttp://localhost:9001/admin/ui/ (React SPA embedded in the AS binary)Exploring, one-off setup, visual confirmation
CLIauthserver admin <subcommand>Local development, scripting, single-host operators
REST APIPOST /admin/... against :9001CI/CD pipelines, infrastructure-as-code, multi-environment provisioning

Auth applies uniformly: the CLI and REST API use the AUTHPLANE_ADMIN_API_KEY env var (or YAML admin.api_key). The Admin UI uses session login.

Only the OIDC federation provider config and the global xaa.* toggles are YAML-only at v0.1.x. XAA trusted IdPs, policies, and subject mappings are managed through the admin REST API (/admin/idps, /admin/xaa/policies, /admin/xaa/subject-mappings) — each topology page calls that out where it applies.

Visual conventions

Every topology diagram in these docs uses the same node names:

NodeWhat it is
UserHuman user, typically in a browser
AgentMCP agent — Claude Code, Claude Desktop, Cursor, ChatGPT, custom
ASAuthPlane authorization server
MCPA Mint resource (AS signs the token)
BrokerA Broker resource (AS vends an upstream IdP token)
IdPUpstream identity provider (Google, Okta, Entra)
BackendBackend service authenticating as itself
GatewayAn MCP that proxies to other resources

Edge labels carry the wire payload: token bound to <slug>, grant=client_credentials, RFC 8693 exchange. Subgraphs mark encapsulation boundaries (e.g. “invisible to AS”).