Technical Overview

A concise, evaluator-level description of how the Headless Auth Platform is built and secured. For the what/why in plain language, see Getting started; for the full requirements and design, see the project specification under specs/001-headless-auth-platform/.

All capabilities described here are implemented today. Items not yet built are listed under Roadmap and are clearly labeled.

Architecture at a glance

The platform is a single, API-first backend service — there is no shipped UI. Integrating applications call typed REST endpoints; an OpenAPI 3.1 document is generated from the code as the contract.

            ┌─────────────────────────────────────────────────┐
 Your apps ─┤  Headless Auth Platform (FastAPI, async)        │
  (REST)    │   ├── api/v1        OAuth/OIDC, auth, mfa,      │
            │   │                 webauthn, sessions, scim,   │
            │   │                 webhooks, rbac, admin       │
            │   ├── domain        identities, credentials,    │
            │   │                 tokens, sessions, oauth,    │
            │   │                 federation, saml, risk      │
            │   ├── crypto        keys (KMS-pluggable),       │
            │   │                 JWT, hashing, encryption    │
            │   └── core          tenant context, errors,     │
            │                     audit, rate limiting        │
            └──────────────┬───────────────┬──────────────────┘
                           │               │
                    PostgreSQL 16        Redis 7
              (source of truth,     (sessions/revocation,
               partitioned audit)    OTP/PKCE state, locks)

Language/runtime: Python 3.12, FastAPI (async), served by Uvicorn/Gunicorn.
Data: PostgreSQL 16 (primary store; login_attempts and audit_log are time- partitioned). Redis 7 for ephemeral state, rate-limit counters, the token-revocation fast path, and refresh-rotation locks.
Async work: Celery (Redis broker) for background delivery jobs.
Packaging: uv for reproducible installs; Docker + Compose for self-hosting.

Standards implemented

OAuth 2.0 (RFC 6749) with PKCE S256 required (RFC 7636 / 9700 hardening).
OpenID Connect Core + Discovery (ID tokens, user-info, JWKS).
SAML 2.0 assertions — consumed (SP) and issued (IdP), signed via XML-DSig.
WebAuthn Level 2 / FIDO2 for passkeys.
SCIM 2.0 (RFC 7643/7644) for user provisioning.
JWT/JWS/JWK (RFC 7519/7515/7517) for tokens and key publication.

Security model

No custom cryptography. Vetted libraries handle JWT, WebAuthn, SAML, password hashing, and TOTP.
Token signing keys never touch the database. A pluggable KeyProvider (env / AWS KMS / Vault) resolves keys; only opaque references are stored. JWT algorithms are restricted to RS256/ES256/EdDSA — alg:none is rejected.
Passwords: Argon2id by default; legacy hashes verified and transparently re-hashed. Account lockout on repeated failures.
Tokens: short-lived access/ID tokens; opaque refresh tokens with rotation and replay-detection (a reused refresh token revokes the whole family). Access-token revocation is immediate via a Redis revocation set.
PKCE-only, exact redirect-URI matching, no implicit/password grants, no query-string bearer tokens — the well-known OAuth hardening rules are enforced.
Multi-tenant isolation: every record is tenant-scoped; cross-tenant access is prevented structurally, and each tenant has its own signing keys and policies.
Auditability: every mutating operation writes to an append-only, partitioned audit_log, which can be streamed to a SIEM.
Assurance levels (AAL): sessions track AAL; sensitive actions can require step-up.

Data model (high level)

Fourteen entity groups, normalized in PostgreSQL. The most important:

Entity	Purpose
Tenant	Isolation root: policies, branding, signing keys.
Application	An OAuth/OIDC client or SAML SP (client id, redirect URIs, scopes).
Identity	An end user within a tenant (no credential material stored here).
Credential	A polymorphic auth factor: password, passkey, TOTP, or social link.
Session	A server-side login session with AAL and a refresh-token family.
VerificationToken	Single-use, hashed tokens (email verify, reset, auth codes, OTP).
LoginAttempt	Time-partitioned record of every attempt + risk signals.
AuditLog	Time-partitioned, append-only audit trail.
Identity Provider, Consent, Role/RoleAssignment, Webhook, AI Suggestion	Federation, consent, RBAC, and operations.

Full DDL and rationale: specs/001-headless-auth-platform/data-model.md.

Quality & verification

68 automated tests, run against real PostgreSQL + Redis (via testcontainers), plus strict type checking (mypy --strict) and linting (ruff). See testing.md for the plain-language breakdown and the full per-test appendix.
The OpenAPI document is regenerated in CI and checked for drift against the code.

Deployment

Self-host with Docker Compose (app + PostgreSQL + Redis + Celery workers); see the Installation guide. A managed option is available — contact us.

Roadmap

Not yet available (do not assume these in an evaluation): LDAP/AD direct login; OAuth device-code grant; formal compliance certification (today the platform provides supporting controls and audit evidence, not an attestation); SAML SP-initiated AuthnRequest & SLO; live session-anomaly step-up; audit retention age-out; login-endpoint rate limiting; scoped admin-key issuance; fully asynchronous notification delivery; independently load- validated performance figures (a design target exists).