qauth

QAuth is an open-source OAuth 2.1 and OpenID Connect 1.0 server. You run it
yourself. Your apps, MCP servers and AI agents get standard access tokens and
ID tokens from it.

It is built for three jobs:

• Agents. An AI agent acts for a user with narrower rights than the user,
  and every step is audited (ADR-007).
• Federation. Identity sources plug in behind one interface. Apps
  integrate once, whatever the user signs in with
  (ADR-003).
• Post-quantum. Signing sits behind algorithm-agnostic interfaces. A
  hybrid ML-DSA-65 + Ed25519 mode already ships
  (ADR-005).

Status

QAuth is pre-1.0. Releases are 0.x, and main runs ahead of the latest one.
The changelog lists every change.

The road to 1.0 runs through 0.x betas, one area at a time: the core and its
UIs, then the Authority Tree, then federation.
ADR-018 sets what 1.0 covers and
what it promises. An independent security audit and OpenID Foundation
certification come before 1.0.

The status page tracks each
feature. The milestones hold
the open work.

What works today

OAuth 2.1 and OpenID Connect

• Authorization code flow with mandatory PKCE (S256), for confidential and
  public clients.
• client_credentials and refresh_token grants. Refresh tokens rotate, and
  a replayed one revokes its whole family.
• Discovery, JWKS, ID tokens, userinfo, introspection (RFC 7662) and
  revocation (RFC 7009).
• RP-initiated logout: an app sends the browser to /oauth/end-session to
  sign it out, and gets it back at a URI it registered. Without a valid
  id_token_hint for the signed-in account, the person confirms first.
• Back-channel logout: whenever a session ends, each app it signed in to that
  registered a backchannel_logout_uri gets a signed logout token there,
  queued with the sign-out and retried while the app is unreachable.
• Resource indicators (RFC 8707): each token is bound to its audience.
• Client registration by Client ID Metadata Document (CIMD). RFC 7591 dynamic
  registration remains as a fallback.

MCP servers and AI agents

• The MCP authorization profile, revision 2026-07-28: protected-resource
  metadata (RFC 9728), audience binding and step-up challenges.
  @qauth-labs/resource-guard handles
  the resource-server side.
• An agent client type. An agent acts for a user through token exchange
  (RFC 8693), and the act claim names it.
• Scope modes (read-only, admin, exec), step-up before dangerous operations,
  and an audit trail per agent.
• A policy per environment (development, staging, production). It sets token
  lifetimes, PKCE, redirects, rate limits and step-up
  (ADR-008).

Accounts and operations

• Email and password sign-up with account verification. Passwords are hashed
  with Argon2id. Repeated failed logins lock the account.
• Sign-in, and sign-up when a realm allows it (ALLOW_SIGN_UP), through a
  realm's upstream OpenID Connect providers: a button per provider on the
  sign-in page, or qauth_upstream=<type> on the authorization request. An
  account is found by the provider's subject under its issuer, never matched by
  email. Providers are stored in realm_upstream_providers; the admin API to
  manage them is still to come.
• Realms: separate tenants, each with its own issuer and hosts.
• A developer portal for OAuth clients and API keys.
• Security headers, CSRF protection and __Host- cookies.
• Structured logs, liveness and readiness probes (/health, /ready), and
  Prometheus metrics on an internal listener. Events can also go out as
  OpenTelemetry logs, once OTEL_EVENTS_ENABLED is set.
• Signing keys stored encrypted under a key-encryption key (KEK).

Behind switches that are off by default

Quick start

You need Docker 23 or later with Compose 2, and OpenSSL.

git clone https://github.com/qauth-labs/qauth.git
cd qauth
cp .env.docker.example .env

Fill in these values in .env:

Then start the stack and check it:

docker compose up -d
curl http://localhost:3000/ready

Compose builds the images from source and runs the database migrations. It
then starts the auth server on port 3000 and the developer portal on port
3001, with PostgreSQL 18 and Redis 7. The interactive API docs at /docs are
off in production; ENABLE_SWAGGER=true turns them on.

The Docker guide covers the
development setup and troubleshooting.

Documentation

Guides and reference live at docs.qauth.dev:

In this repository:

• docs/adr/: the architecture decision records.
• docs/security/threat-model.md: what
  QAuth promises and how findings are rated.
• docs/: the other engineering records, such as the
  spec pin log and the conformance matrix.
• Each library documents itself in its own README.md under libs/.

Repository layout

The stack is TypeScript on Node.js 26: Fastify, Drizzle ORM, PostgreSQL 18 and
Redis 7 on the server; React 19 and TanStack Start for the UIs. The monorepo
runs on Nx and pnpm.

Contributing

CONTRIBUTING.md covers setup, conventions and the pull
request checklist. Everyone who takes part follows the
Code of Conduct.

Security

Report a vulnerability privately, as SECURITY.md describes.
Please do not open a public issue for it.

License

Apache License 2.0. See LICENSE.

Copyright © 2025–2026 QAuth Labs

Acknowledgments

QAuth learns from the open-source identity servers that came before it. It
builds on the open standards of the IETF, the OpenID Foundation, the W3C and
NIST.

Website · Documentation ·
Foundation