authserver

module

v0.1.0 Latest Latest Go to latest Published: Jun 11, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/authplane/authserver

Links

Open Source Insights

README ¶

Authplane

The self-hosted authorization server for the Model Context Protocol.

One Go binary. AGPL-3.0. MCP Authorization spec 2025-11-25, end-to-end.

AI coding agents: read AGENTS.md first — it has the deterministic workflow for adding Authplane to an existing MCP server, the SDK pins per stack, and the three byte-for-byte rules that cause >90% of invalid_token failures. If you're an agent operating from web docs (no clone), llms.txt is the same link map in the llmstxt.org convention.

Why Authplane

Building an MCP server is now a one-afternoon job. Securing it isn't. You need to issue tokens, validate them, federate to your existing IdP, and let agents act on each other's behalf without losing the user behind the chain. Authplane is the one piece of infrastructure that answers all of that.

Spec-compliant access tokens for any MCP server in any language — discovery, scopes, audience binding, refresh rotation, in token formats your existing resource servers already understand.
Federation to your existing IdP — Google, Okta, Azure AD, Auth0, anyone OIDC-compliant. Authplane handles the OAuth side; you keep the access policy.
Agent-to-agent delegation — one agent calls another on a user's behalf, with every hop recorded as an act-claim chain in the issued token and the audit log.
Upstream provider vaulting — store GitHub / Google / Slack / Linear refresh tokens encrypted at rest and vend fresh access tokens via RFC 8693, with per-user / per-agent / per-resource consent enforced at every hop.
DPoP proof-of-possession — bind tokens to a client-held key so a leaked token can't be replayed from another machine.
Built-in Admin UI — React dashboard embedded in the same binary. No separate frontend, no extra container.
Production storage and observability — PostgreSQL with cross-instance LISTEN/NOTIFY, OpenTelemetry traces and metrics, Prometheus, Helm chart, Vault Transit for HSM-grade signing.
Zero-config dev — default SQLite, auto-generated signing keys, sensible defaults.

(Full RFC inventory at the bottom — Standards & Specifications.)

Quick Start

One docker run. A working OAuth 2.1 + MCP authorization server in under a minute.

export AUTHPLANE_ADMIN_API_KEY="$(openssl rand -hex 32)"
export AUTHPLANE_SESSION_SECRET="$(openssl rand -hex 32)"
echo "Save this — it's your Admin UI login: $AUTHPLANE_ADMIN_API_KEY"

docker run -p 9000:9000 -p 9001:9001 \
  -e AUTHPLANE_ADMIN_API_KEY \
  -e AUTHPLANE_SESSION_SECRET \
  -e AUTHPLANE_CLIENT_CREDENTIALS_ENABLED=true \
  -e AUTHPLANE_DPOP_ENABLED=true \
  -e AUTHPLANE_TOKEN_EXCHANGE_ENABLED=true \
  -v authserver-data:/data \
  authplane/authserver:latest serve

Open http://localhost:9001/admin/ui/ and paste the printed API key. The public OAuth endpoints are on http://localhost:9000.

Next: register your first MCP server

Writing an MCP server from scratch? Start at the runnable example for your language — Python · TypeScript · Go. Auth in 5 lines, end-to-end smoke in make verify.
Adding auth to an MCP server you already have? The retrofit example is a runnable before/after pair — same three tools in two versions, side-by-side, with a smoke-test that proves before accepts anything and after enforces auth. Python · TypeScript · Go. Or read the Connect an MCP Server guide for the prose version.
Already have an MCP server running elsewhere? To point this AS at your server and drive the whole OAuth flow by hand with curl — no SDK, no compose — see Run the AS standalone and point it at your own MCP server. It also reconciles this Quick Start's config with the examples/ .env style.
Operator quickstart (upstream providers, PostgreSQL, OIDC federation, Helm, multi-instance): docs/README.md.
Building from source: CONTRIBUTING.md.

The Admin UI

Authplane Admin UI

Manage everything from a browser. The Admin UI is embedded in the same binary; every operation is also exposed via the Admin REST API.

SDKs

Authserver is only half the story. The MCP server on the other side still has to validate the tokens, expose the discovery endpoint, enforce scopes per tool, handle DPoP, and decode consent errors. The Authplane SDKs do all of that in 5 lines of integration code — measured, CI-counted, in Python / TypeScript / Go alike. The full ladder (basic MCP server → calling another resource → DPoP + per-tool scopes → fronting a Broker upstream) sits between 5 and 30 lines of auth-specific code per tier; see examples/ for the numbers under each tier's banner.

Every Authplane SDK provides the same baseline:

JWT validation against the authserver JWKS, with caching
Scope enforcement, per route or per tool
The Protected Resource Metadata document at /.well-known/oauth-protected-resource/<mcp-path> (RFC 9728, suffixed per the MCP spec)
DPoP proof verification (RFC 9449)
A full OAuth client — Client Credentials, RFC 8693 Token Exchange, Introspection, Revocation
Structured ConsentRequiredError decoding for the upstream-provider Broker flow

Pick the language and the framework adapter that match the stack you're already on.

Language	Repo	Integration Adapters	Docs
Go	authplane/go-sdk	✓ Official MCP Go SDK (`go-sdk/mcp`)	README
TypeScript	authplane/ts-sdk	✓ Official MCP TypeScript SDK (`@authplane/mcp`) ✓ FastMCP (`@authplane/fastmcp`)	README
Python	authplane/python-sdk	✓ Official MCP Python SDK (`authplane-mcp`) ✓ FastMCP (`authplane-fastmcp`)	README
Rust	roadmap	—	—
C#	roadmap	—	—
Java	roadmap	—	—

Working examples wired against authserver live under examples/ — Python / TypeScript / Go, with four tiers each (basic MCP server, calling another resource, DPoP + per-tool scopes, MCP server fronting a Broker). Every example's make verify is exercised by make docs-smoke and the per-tier LOC budget is CI-enforced via tools/loccount.

Integration walkthroughs: Auth Client · Resource Server.

Documentation

For advanced operations and deeper reference, the docs/ tree is organized by audience:


Get started	Quickstart
Configuration	Configuration Guide · Schema Reference
API Reference	HTTP API (all endpoints) · CLI · Audit Events · Metrics
Security	Threat Model · Tokens and Claims · Key Rotation · DPoP
Deployment	Docker Compose · systemd · Kubernetes
Guides	Connect an MCP Server · Admin CLI & API · OIDC Federation · Observability
Grant Types	Client Credentials · Token Exchange · JWT Bearer / XAA · Enterprise-Managed Auth
Architecture	Architecture Overview · Authentication Flows · RFC Compliance
Full Index	Documentation Index

Standards & Specifications

Authplane implements the MCP Authorization specification (2025-11-25) and the OAuth 2.1 ecosystem standards behind it. ("OAuth 2.1" is an active IETF Internet-Draft, not a finalized RFC — the MCP spec itself targets it. See Compliance for the full picture.) Here's what each one gives you, in operator terms:

Standard	What it provides
MCP Authorization 2025-11-25	The contract MCP clients and servers expect: discovery endpoints, dynamic client registration, audience-bound tokens. The reason your existing MCP tooling can find and talk to authserver without custom adapters.
OAuth 2.1	The base authorization flow — authorize endpoint, token endpoint, refresh tokens, scopes. PKCE-S256 is mandatory; the older insecure flows aren't supported.
PKCE (RFC 7636)	Prevents stolen authorization codes from being redeemed. Critical for public clients (CLIs, desktop apps, mobile).
DPoP (RFC 9449)	Binds tokens to a client-held key. A leaked token can't be replayed from another machine.
Resource Indicators (RFC 8707)	Audience-binds every token to a specific resource URI. An access token for one MCP server can't be replayed against another.
Protected Resource Metadata (RFC 9728)	MCP servers advertise where their authorization server lives. Clients discover the AS automatically.
Dynamic Client Registration (RFC 7591)	Clients register themselves at runtime — needed for MCP clients you don't pre-provision. Three security modes: open, approved-redirects, admin-only.
Client ID Metadata Documents (CIMD)	Auto-registration by fetching client metadata from the client's URL. The MCP-native way for agents to identify themselves without a registration round-trip.
OAuth AS Metadata (RFC 8414) + OIDC Discovery	The `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` documents every OAuth client knows how to fetch.
Token Exchange (RFC 8693)	Delegated identity — one client mints a narrower or differently-scoped token from an existing one. Powers the agent-to-agent delegation chain and the upstream-provider Broker flow.
JWT Bearer (RFC 7523)	Trusted external IdPs assert identity directly into Authplane. The foundation for Cross-App Access (XAA) and enterprise federation.
JWT Access Tokens (RFC 9068)	Default token format (`at+jwt`). Every token is a self-contained JWT your resource servers can verify offline against the JWKS.
Token Introspection (RFC 7662)	Runtime token validation endpoint for revocation-aware verification.
Token Revocation (RFC 7009)	Standard endpoint to revoke refresh tokens and their families.

Status & roadmap

Authplane is in active development. v0.1.x is production-shaped — the OAuth core, MCP discovery, and audit log are spec-compliant and tested. A few things to set expectations:

Rust, C#, and Java SDKs are on the roadmap; Go, TypeScript, and Python are released.
Upstream-provider connections (Broker flow) require manual configuration of at-rest encryption (aes_master or HashiCorp Vault Transit) before they activate — covered in docs/guides/upstream-providers/connecting-providers.md.
Multi-tenant isolation today means running separate instances per tenant. A first-class tenant abstraction is post-v1.0.
Public dynamic-registration signup UI is not in v0.1; Dynamic Client Registration works over HTTP today, a hosted signup page is a follow-up.
Helm chart (charts/authplane) is at v0.1.0; tested for single-instance and basic HA, expect tuning for large fleets.

If something here blocks your deployment, open an issue — the priority list is informed by what you're trying to ship.

License

AGPL-3.0-or-later — see LICENSE.

Need a different licence?

We'd love to hear from you — write to hello@authplane.ai and let's find one that fits.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
admin Package admin provides the admin API HTTP server.	Package admin provides the admin API HTTP server.
public Package public provides the public-facing HTTP server, assembling routes from the oauth, vault, and wellknown sub-packages.	Package public provides the public-facing HTTP server, assembling routes from the oauth, vault, and wellknown sub-packages.
public/connection Package connectionapi serves the user-facing /connect/{provider} and /connections routes that orchestrate the upstream-Broker connect dance.	Package connectionapi serves the user-facing /connect/{provider} and /connections routes that orchestrate the upstream-Broker connect dance.
public/oauth Package oauth provides OAuth authorization and token HTTP handlers.	Package oauth provides OAuth authorization and token HTTP handlers.
public/wellknown Package wellknown provides discovery and infrastructure endpoints: JWKS, AS metadata, Protected Resource Metadata, health, and metrics.	Package wellknown provides discovery and infrastructure endpoints: JWKS, AS metadata, Protected Resource Metadata, health, and metrics.
shared Package shared provides middleware and error helpers used by both the public and admin HTTP servers.	Package shared provides middleware and error helpers used by both the public and admin HTTP servers.
cmd
authserver command Package main is the entrypoint for the authserver binary.	Package main is the entrypoint for the authserver binary.
internal
adapters/aesmaster Package aesmaster implements the DataEncryptor port using AES-256-GCM with HKDF-SHA256 per-value key derivation from a master key.	Package aesmaster implements the DataEncryptor port using AES-256-GCM with HKDF-SHA256 per-value key derivation from a master key.
adapters/brokerproto/apikey Package apikey implements the BrokerProtocol port for upstream services where the user supplies a long-lived API key (e.g.	Package apikey implements the BrokerProtocol port for upstream services where the user supplies a long-lived API key (e.g.
adapters/brokerproto/oauth Package oauth implements the BrokerProtocol port for upstream OAuth 2.0 providers — the upstream-facing OAuth dance (authorize URL + code exchange) plus refresh-token vending.	Package oauth implements the BrokerProtocol port for upstream OAuth 2.0 providers — the upstream-facing OAuth dance (authorize URL + code exchange) plus refresh-token vending.
adapters/brokerproto/serviceaccount Package serviceaccount implements the BrokerProtocol port for upstream providers where the AS holds a service-account private key and impersonates a specific user via an outbound RFC 7521 §4.2 / RFC 7523 §2.1 JWT bearer assertion (e.g.	Package serviceaccount implements the BrokerProtocol port for upstream providers where the AS holds a service-account private key and impersonates a specific user via an outbound RFC 7521 §4.2 / RFC 7523 §2.1 JWT bearer assertion (e.g.
adapters/cimd Package cimd provides an HTTP-based Client ID Metadata Document fetcher.	Package cimd provides an HTTP-based Client ID Metadata Document fetcher.
adapters/encryption Package encryption provides a factory for creating the configured DataEncryptor backend.	Package encryption provides a factory for creating the configured DataEncryptor backend.
adapters/hcvault Package hcvault implements key storage and data encryption using HashiCorp Vault Transit.	Package hcvault implements key storage and data encryption using HashiCorp Vault Transit.
adapters/idpjwks Package idpjwks provides a JWKS fetcher and cache for trusted IdP issuers.	Package idpjwks provides a JWKS fetcher and cache for trusted IdP issuers.
adapters/keyfile Package keyfile implements key storage using PEM files on disk.	Package keyfile implements key storage using PEM files on disk.
adapters/oidc Package oidc implements upstream OIDC federation using net/http + go-jose/v4.	Package oidc implements upstream OIDC federation using net/http + go-jose/v4.
adapters/postgres Package postgres provides PostgreSQL implementations of the output port interfaces.	Package postgres provides PostgreSQL implementations of the output port interfaces.
adapters/signing Package signing provides a factory for creating the configured KeyStore backend.	Package signing provides a factory for creating the configured KeyStore backend.
adapters/sqlite Package sqlite provides SQLite implementations of the output port interfaces.	Package sqlite provides SQLite implementations of the output port interfaces.
adapters/storage Package storage provides a factory for creating the configured DataStore backend.	Package storage provides a factory for creating the configured DataStore backend.
admin/dto Package dto holds the JSON wire-shape views for the unified-resource admin surface.	Package dto holds the JSON wire-shape views for the unified-resource admin surface.
brokerproto Package brokerproto holds the BrokerProtocol adapter registry that internal/services/broker_issuer.go consults at request time to dispatch upstream-token vending by protocol name.	Package brokerproto holds the BrokerProtocol adapter registry that internal/services/broker_issuer.go consults at request time to dispatch upstream-token vending by protocol name.
config Package config provides configuration loading and validation for authserver.	Package config provides configuration loading and validation for authserver.
crypto Package crypto provides cryptographic primitives for authserver.	Package crypto provides cryptographic primitives for authserver.
domain Package domain contains shared domain types and errors.	Package domain contains shared domain types and errors.
domain/audit Package audit contains the Event domain entity.	Package audit contains the Event domain entity.
domain/client Package client contains the Client domain entity for OAuth 2.1 clients.	Package client contains the Client domain entity for OAuth 2.1 clients.
domain/idp Package idp contains the TrustedIDP domain entity for XAA enterprise-managed authorization.	Package idp contains the TrustedIDP domain entity for XAA enterprise-managed authorization.
domain/resource Package resource contains domain types for the unified Resource registry and its companion shapes.	Package resource contains domain types for the unified Resource registry and its companion shapes.
domain/scope
domain/session Package session contains the AuthSession domain entity.	Package session contains the AuthSession domain entity.
domain/token Package token contains the Family and RefreshToken domain entities.	Package token contains the Family and RefreshToken domain entities.
domain/user Package user contains the User domain entity.	Package user contains the User domain entity.
domain/xaa Package xaa provides domain types for Enterprise-Managed Authorization (Cross App Access) policies and subject mappings.	Package xaa provides domain types for Enterprise-Managed Authorization (Cross App Access) policies and subject mappings.
issuer Package issuer holds the Issuer registry consulted by internal/services/token_exchange.go at request time to dispatch token issuance by Resource.BackendKind.	Package issuer holds the Issuer registry consulted by internal/services/token_exchange.go at request time to dispatch token issuance by Resource.BackendKind.
observability Package observability provides unified logging, tracing, and metrics.	Package observability provides unified logging, tracing, and metrics.
ports/input Package input defines the driving ports — what the outside world asks the system to do.	Package input defines the driving ports — what the outside world asks the system to do.
ports/output Package output defines the driven ports — what the system needs from the outside world.	Package output defines the driven ports — what the system needs from the outside world.
services Package services contains application services.	Package services contains application services.
ssrf Package ssrf provides SSRF-safe HTTP transport that blocks connections to private/reserved IP addresses.	Package ssrf provides SSRF-safe HTTP transport that blocks connections to private/reserved IP addresses.
migrations
postgres Package postgres provides embedded PostgreSQL migration files.	Package postgres provides embedded PostgreSQL migration files.
sqlite Package sqlite embeds SQL migration files for the SQLite backend.	Package sqlite embeds SQL migration files for the SQLite backend.
tools
docsgen command Package main implements docsgen: a small CLI that generates reference documentation (CLI flags, HTTP API, environment variables, configuration) for the Authplane authserver by inspecting the source tree.	Package main implements docsgen: a small CLI that generates reference documentation (CLI flags, HTTP API, environment variables, configuration) for the Authplane authserver by inspecting the source tree.
docsgen/cmd openapi.go — generate OpenAPI 3 YAML for the public + admin servers from the same handler/DTO AST walk that produces docs/reference/http-api.md.	openapi.go — generate OpenAPI 3 YAML for the public + admin servers from the same handler/DTO AST walk that produces docs/reference/http-api.md.
docsgen/internal/configast Package configast provides an AST-driven model of the authserver's configuration package.	Package configast provides an AST-driven model of the authserver's configuration package.
docsgen/internal/mdwriter Package mdwriter contains small, pure helpers for building Markdown fragments: tables, fenced code blocks, anchors and sections.	Package mdwriter contains small, pure helpers for building Markdown fragments: tables, fenced code blocks, anchors and sections.
docsgen/internal/srcref Package srcref formats AST positions as repo-relative "file:line" references suitable for embedding in generated reference docs.	Package srcref formats AST positions as repo-relative "file:line" references suitable for embedding in generated reference docs.
docslinks command docslinks walks every Markdown file in the repo and verifies that inline links of the form `[text](path)` or `[text](path#fragment)` resolve: the target file exists, and any `#fragment` matches either an explicit `<a id="fragment"></a>` element or a heading whose GitHub slug matches the fragment.	docslinks walks every Markdown file in the repo and verifies that inline links of the form `[text](path)` or `[text](path#fragment)` resolve: the target file exists, and any `#fragment` matches either an explicit `<a id="fragment"></a>` element or a heading whose GitHub slug matches the fragment.
loccount command Package main implements loccount: a small CLI that counts auth-specific lines of code inside marked regions in example projects and renders a summary banner in each example's README.md.	Package main implements loccount: a small CLI that counts auth-specific lines of code inside marked regions in example projects and renders a summary banner in each example's README.md.
web
admin Package webadmin provides the embedded admin UI static files.	Package webadmin provides the embedded admin UI static files.