Skip to content

README.md

Latest commit

 

History

History
82 lines (61 loc) · 10.1 KB

README.md

File metadata and controls

82 lines (61 loc) · 10.1 KB
Raw

QAuth Documentation

QAuth is the open-source, self-hostable OAuth 2.1 authorization server for MCP servers and AI agents (see ADR-007). This is the entry point to the guides; the canonical, always-current API surface is the interactive Swagger UI at /docs on any running instance.

🎉 June 2026 — MVP complete and the agent-native authorization layer shipped (agent client type, RFC 8693 on-behalf-of delegation, scope modes, step-up, per-agent audit), alongside the T3 production-hardening track and the T5 environment-aware authorization posture (ADR-008). Start with the agent-authorization guide.

Getting started

Guide What it covers
MCP Quickstart End-to-end: run QAuth, run a mcp-guard-protected MCP resource server, and complete the full discovery → register → authorization_code + PKCE → token handshake. Start here.
Docker Guide Running the stack (auth-server + Postgres + Redis) in development and production; environment variables; CIMD configuration.
Observability Structured logging + secret redaction, request-id tracking, auth-event logging, failed-login lockout, the Prometheus GET /metrics endpoint, and recommended Alertmanager rules.
Browser Security The browser-facing hardening (T3): security headers (nonce-based CSP, HSTS, X-Frame-Options), CSRF double-submit protection, __Host- secure cookies, and XSS-safe HTML output.

OAuth 2.1 / OIDC

Guide What it covers
OAuth 2.1 Flow Every endpoint with copy-paste curl: PKCE generation, /oauth/authorize, token exchange, refresh-token rotation, client_credentials, introspection, UserInfo, and Dynamic Client Registration.
ADR-006: OAuth grants & audience Why client_credentials + client_secret_basic and per-client aud binding work the way they do.

Post-quantum signing

Guide What it covers
Hybrid Signing — Verifier Guide How token verifiers behave during the ADR-005 hybrid (Ed25519 + ML-DSA-65) rollout: the mixed OKP+AKP JWKS, the reference-token/introspection delivery default, the draft-revision churn risk, and a migration checklist. No action is required for classical Ed25519-only verifiers.
ADR-005: PQC Hybrid Signing The post-quantum roadmap, the detached-parallel construction, and the #243–248 implementation amendments.
Security Gate Review The three-dimension security review of the merged PQC surface (CONDITIONAL PASS) and the pre-default-on checklist.

Agent authorization

Guide What it covers
Agent Authorization The agent-native layer (ADR-007 §2): the agent client type (is_agent), RFC 8693 Token Exchange / on-behalf-of delegation (act claim), agent scope modes (ReadOnly / Admin / Exec + the operator-set cap), step-up authentication before dangerous operations, and per-agent audit.

API reference

Guide What it covers
API Reference Hand-written contract for every endpoint: first-party auth (/auth/*), OAuth 2.1 (/oauth/*), discovery, and client management (/api/clients), with request/response shapes, status codes, and the error envelope.

The authoritative, always-current surface is the live OpenAPI / Swagger UI at /docs on the running instance. Also:

Code examples

Guide What it covers
Code Examples Copy-paste-ready clients — Node/TS (first-party register→login→protected call; machine client_credentials) and browser JS (authorization_code + PKCE with Web Crypto).

Environment-aware authorization

Guide What it covers
Environment-Aware Authorization Operator/how-to guide: the environment (development / staging / production) policy dimension on clients/realms, the profile table, fail-safe defaults, and environment-gated developer API keys (T5).
ADR-008: Environment-aware authorization The design decision behind the above — fail-safe reasoning, the resolveEnvironmentPolicy resolver, and prior-art comparison.

Architecture & decisions