Architecture

This chapter describes the overall structure of Ahdapa, the key modules, and the full request lifecycle from a TCP connection to an HTTP response.

System architecture

graph TB
    subgraph clients["OAuth2 Clients / Browsers"]
        browser["Browser (Authorization Code)"]
        device["CLI / IoT (Device Flow)"]
        service["Service (Client Credentials)"]
    end

    subgraph ahdapa["Ahdapa Node"]
        direction TB
        oauth2["OAuth2 endpoints\n/authorize · /token · /jwks\n/revoke · /introspect · /userinfo\n/par · /device_authorization"]
        saml2["SAML2 endpoints\n/saml2/metadata · /saml2/sso\n/saml2/slo · /saml2/acs\n/saml2/sp/metadata · /saml2/auth\n/saml2/artifact · /saml2/slo/start"]
        auth["Auth module\nGSSAPI/SPNEGO · Password\nSession cookie · AEAD codes"]
        crdt["CRDT state\nIdpCrdt (RwLock)\nsigning keys · clients · nodes\nSAML2 SP/IdP entries"]
        db[("Local DB\nSQLite / Postgres / MariaDB\nCRDT snapshots + ephemeral tables")]
        webui["WebUI\nPreact SPA\n/ui/auth/* · /ui/admin/*"]
        admin["Admin API\n/api/admin/*\nclients · keys · nodes · families\nSAML2 SP/IdP management"]
        gossip["Gossip loop\n/api/gossip/sync\nCMS (ML-KEM-768 + ECDSA P-256)"]
    end

    subgraph infra["FreeIPA Infrastructure"]
        kdc["KDC (Kerberos)"]
        ldap["LDAP (FreeIPA)"]
    end

    subgraph peers["Peer Nodes"]
        node2["Ahdapa Node 2"]
        node3["Ahdapa Node 3"]
    end

    subgraph saml_ext["SAML2 Peers"]
        saml_sp["SAML2 Service Providers"]
        saml_idp["Upstream SAML2 IdPs"]
    end

    browser -->|"HTTPS"| oauth2
    browser -->|"HTTPS"| saml2
    device --> oauth2
    service --> oauth2
    oauth2 --> auth
    saml2 --> auth
    auth -->|"GSSAPI token"| kdc
    auth -->|"user lookup"| ldap
    oauth2 --> crdt
    saml2 --> crdt
    crdt --> db
    admin --> crdt
    gossip -->|"POST /api/gossip/sync"| node2
    gossip -->|"POST /api/gossip/sync"| node3
    crdt --> gossip
    webui --> oauth2
    webui --> admin
    saml_sp -->|"AuthnRequest"| saml2
    saml2 -->|"AuthnRequest"| saml_idp
    saml_idp -->|"SAML Response"| saml2

Source layout

src/
  main.rs          Entry point: load config, open DB, build AppState, start gossip, serve
  config.rs        TOML configuration structs (Config, ServerConfig, DbConfig, …)
  audit.rs         Audit event taxonomy (19 event types), recording, overflow/alarm policies,
                   journal query (journalctl subprocess or in-memory/file fallback)
  journal.rs       JournalWriter: systemd journal namespace via Unix datagram, JSONL file
                   fallback, in-memory daemon for tests
  crdt/
    mod.rs         IdpCrdt and the four CRDT primitives: GrowSet, LwwRegister, OrMap, LwwMap;
                   load_from_db / persist_to_db / merge
  db/
    mod.rs         Database initialization (open, migrations, WAL mode)
    schema.rs      Row types mirroring every CRDT and ephemeral table
  auth/
    mod.rs         AuthResult enum; AuthError; public re-exports
    aead.rs        AES-256-GCM seal / open helpers (native-ossl)
    code.rs        Authorization code payload: AEAD-encrypted JSON blob
    consent.rs     Consent cookie payload: AEAD-encrypted pending authorization state
    cookie.rs      Session cookie: seal / unseal (SessionClaims)
    gssapi.rs      SPNEGO acceptor via ahdapa-gssapi
    ipa.rs         FreeIPA attribute lookup: IPA JSON-RPC API (default) or LDAP direct
    passkey.rs     WebAuthn passkey assertion/registration verification; COSE↔SPKI DER conversion
    password.rs    Password-based authentication via LDAP simple bind
    pkce.rs        PKCE S256 code_challenge / code_verifier verification
    refresh.rs     Refresh token payload: AEAD-encrypted, rotation + replay detection
  routes/
    mod.rs         AppState definition; bootstrap helpers; build() — assembles the axum Router
    oauth2.rs      All OAuth2 / OIDC endpoints (authorize, token, jwks, revoke, …)
    discovery.rs   /.well-known/oauth-authorization-server and /.well-known/openid-configuration
    saml2/         SAML2 endpoints: IdP metadata, SSO, SLO, artifact resolution,
                   SP ACS, SP metadata, SP auth, SP-initiated SLO
    admin.rs       /api/admin/* endpoints (clients CRUD, key rotation, nodes, refresh families,
                   SAML2 SP/IdP management)
    gossip.rs      /api/gossip/sync handler and background gossip loop
    topology.rs    FreeIPA topology-based gossip peer discovery (ipa_topology)

webui/
  index.html       Entry HTML — inline script for flash-free theme application
  src/             Preact + TypeScript source
    main.tsx       Preact entry point — wraps App with ThemeProvider, ToastProvider
    App.tsx        React Router setup (basename="/ui")
    api.ts         Typed fetch helpers for admin and auth APIs
    pf.tsx         Custom PatternFly 6 component library (cx, NavSection, Breadcrumb,
                   Pagination, Modal with focus trap, FormSelect, Table, etc.)
    theme.tsx      ThemeProvider / useTheme() — dark mode with localStorage persistence
    toast.tsx      ToastProvider / useToast() — portal-based PF6 AlertGroup notifications
    auth/          User-facing auth pages (Login, Consent, Device, Error)
    admin/         Operator admin pages and AdminLayout (nav groups, breadcrumb, branding)
    user/          User self-service pages (ProfilePage)
  dist/            Built SPA (generated by `npm run build`)

migrations/
  sqlite/0001_initial.sql    SQLite DDL
  postgres/0001_initial.sql  Postgres DDL
  mariadb/0001_initial.sql   MariaDB DDL

crates/
  ahdapa-gssapi/  Safe Rust GSSAPI bindings (fork of akamu-gssapi)
  ahdapa-jose/    JWT signing / verification primitives (fork of akamu-jose)
  ahdapa-ldap/    Safe Rust OpenLDAP bindings (fork of akamu-ldap)
  ahdapa-saml2/   SAML2 protocol library: data model, XML serialization (quick-xml),
                  binding codecs (HTTP-Redirect, HTTP-POST, Artifact), xmlsec1 FFI
                  (sign_xml, verify_xml_signature — called from SSO, ACS, and SLO
                  route handlers)
  hbac-crdt/       Identity HBAC policy engine: op-based CRDT rule set, OAuth2 evaluation

AppState

Defined in src/routes/mod.rs. Every axum handler receives a clone of AppState via axum’s State extractor. Cloning is cheap: all fields are Arc<T>.

Request lifecycle

1. TCP accept and HTTP parsing

tokio accepts a TCP connection. axum passes it to the hyper HTTP/1.1 codec. TraceLayer emits a tracing span for each request.

2. Route dispatch

axum matches the request against the router assembled in routes::build:

3. Authorization code flow

sequenceDiagram
    participant B as Browser
    participant A as Ahdapa
    participant IDP as Auth (SPNEGO/Password)

    B->>A: GET /authorize (PKCE code_challenge)
    A->>IDP: SPNEGO attempt (401 Negotiate) or session cookie check
    alt Unauthenticated
        A-->>B: redirect to /ui/auth/login
    else Authenticated + skip_consent
        A->>A: build AuthCodePayload → AEAD-encrypt
        A-->>B: redirect to redirect_uri
    else Authenticated + consent required
        A->>A: build ConsentPayload → seal as AEAD cookie
        A-->>B: redirect to /ui/auth/consent
        B->>A: GET /api/auth/consent
        A-->>B: display client name + scopes
        B->>A: POST /api/auth/consent {allow: true}
        A->>A: decrypt consent cookie → build AuthCodePayload → AEAD-encrypt
        A-->>B: return redirect_to URL
    end

    B->>A: GET {redirect_uri}?code=…&iss=…

    participant C as Client
    C->>A: POST /token (code + code_verifier)
    A->>A: decrypt auth code → verify PKCE
    A-->>C: JWT access token + refresh token

4. Token issuance

All tokens are issued in routes/oauth2.rs. The actual cryptographic primitives live in src/auth/:

• JWT access token — signed with the active JWT signing key from the CRDT (algorithm set by [server] jwt_signing_algorithm, default ES256).
• Authorization code — AuthCodePayload sealed with AppState::wrapping_key() (the first element of key_pair_rw) via auth::aead.
• Refresh token — RefreshTokenPayload sealed with AppState::refresh_key() (the HKDF-derived second element of key_pair_rw).
• Session cookie — SessionClaims sealed with AppState::wrapping_key().

5. CRDT read/write

Handlers acquire a read lock for lookups and a write lock only for mutations:

#![allow(unused)]
fn main() {
// Read (non-blocking for other readers):
let crdt = state.crdt.read().await;
let client = crdt.clients.get(&client_id);

// Write (exclusive):
let mut crdt = state.crdt.write().await;
crdt.active_kid.set(kid, now, &state.node_id);
}

After any CRDT mutation, the handler (or gossip handler) calls crdt.persist_to_db(&state.db) to flush the snapshot.

6. Background gossip

A background tokio task (routes::gossip::run) wakes either on a gossip_notify signal (fired immediately after any local CRDT write) or after gossip.interval_secs seconds (passive fallback). It prepares all per-peer payloads under a single CRDT read lock, then sends HTTP POSTs to all peers concurrently via tokio::task::JoinSet, and processes responses sequentially. Wall-clock gossip time is O(max single-peer round-trip) regardless of cluster size. See Gossip Protocol for details.

Technology stack