Aegis

What it is

Aegis is the identity platform my other products integrate for authentication, authorization, and audit. It owns the concerns nobody should rebuild per product: API keys stored only as SHA-256 hashes (raw keys are never persisted), a four-level role hierarchy (Reader, Analyst, Operator, Admin, in ascending privilege), and audit logging that records metadata rather than content.

Priivy is the reference integration: with auth enabled, every analyze, anonymize, deanonymize, and admin call is authenticated and authorized through the aegis layer. Deanonymize, the most privileged operation, is audit-logged before decryption proceeds, and the log stores text length, entity types, and outcome rather than the text itself.

Aegis also ships the shared design system, a navy-glass token set with AAA text contrast at 95%, 70%, and 50% white opacity on navy, that sibling consoles adopt pixel-identically, so moving between products feels like one tool.

Why it matters

Self-hosted security software is dead on arrival without SSO, and enterprise buyers bring their own identity provider: Okta, Entra ID, Auth0, Google Workspace, Keycloak. The approved design spec dated 2026-05-04 adds OIDC login with PKCE and SCIM 2.0 provisioning to the platform across six rollout phases, each shipping working software and independently revertable. Deprovisioning at the IdP immediately revokes every active session, which is the compliance-grade property buyers actually check.

The design treats lockout as a when, not an if. Saving a broken SSO config is impossible: the server dry-runs OIDC discovery before persisting and rejects bad input with 422. A documented break-glass path (an env-var-seeded temporary admin key, tagged in the audit log and counted in Prometheus) covers total lockout. Local admins keep passwords with optional TOTP, so CLI and CI access never depends on the IdP.

Architecture decisions

Pluggable providers behind a trait. A composite provider chains OIDC, then local API keys, then deny, and is swapped atomically with ArcSwap. SSO config reloads at runtime with zero downtime: in-flight requests finish against the previous provider, and every saved config gets a monotonic version with rollback history.

Opaque session cookies, not JWTs. Server-side sessions give instant revocation on SCIM deprovision or admin force-logout without blocklists. IdP refresh tokens are AES-256-GCM encrypted at rest, group claims re-evaluate hourly, and secrets never touch the database: client secrets and SCIM bearer tokens are environment or Vault references, compared in constant time.

Deliberate non-goals, written down rather than forgotten: SAML 2.0 (bridged through the IdP when required), multi-tenant SSO (one IdP per installation), WebAuthn for local admins, and IdP-initiated flows. OIDC and SCIM live in their own crates, roughly 2-3K lines of protocol code each, tested with mock IdPs, forged tokens, RFC 7644 conformance suites, and fuzzed parsers, because mixing protocol code into HTTP wiring would destroy testability.