Vord

Architecture Decision Record

0017. SAML 2.0 IdP placement and the constitution seam

Context

Competing with Entra ID and Okta for workforce SSO is impossible without SAML 2.0 as an identity provider — a large fraction of enterprise relying parties speak SAML, not OIDC. But SAML sits in apparent tension with the constitution in a way OIDC does not, and that tension is the sharpest conceptual risk in the whole platform. SAML is front-channel (HTTP-Redirect and HTTP-POST bindings through the browser), XML-DSig-signed, and session-heavy; its assertions are not the compact, edge-cacheable, stateless-verifiable artifacts JWTs are, and SSO over SAML implies a server-side login session. A naive reading asks: does SAML force a stateful, core-touching check onto a path the constitution wants stateless? This ADR answers that by placing SAML precisely. It records the decision (the seam) now even though the IdP is built later (a roadmap milestone), because the placement constrains the admission plane's shape and must not be discovered after the fact.

Decision

  1. The SAML IdP is a Modgud front-channel concern (ADR-0009). The SAML SSO and single-logout (SLO) endpoints, assertion construction and XML-DSig signing, and the associated login session (ADR-0016) all live at the admission plane — stateful, issuance-side, permitted to read the core. This is exactly where login ceremonies and OIDC authorization already live; SAML adds a protocol dialect at the same plane, not a new plane.

  2. A SAML assertion is an issuance artifact, not a hot-path verification artifact. It is produced once per login at Modgud and consumed by the service provider (SP). The constitution governs Vör, and no SAML artifact ever reaches Vör. Relying-party validation of a SAML assertion stays per-protocol at the SP, which checks the XML-DSig against Vord's published SAML signing certificate — itself a stateless check against public key material, philosophically the same rule-1 shape as JWKS verification, merely in XML rather than JOSE.

  3. Where Vord controls the downstream, SAML is exchanged into JOSE. A SAML login at Modgud can be token-exchanged (RFC 8693, ADR-0014) into a short-TTL OIDC JWT, so that any Vord-internal resource server, and the edge verification path generally, always see a Vör-verifiable token. SAML is thereby confined to the front-channel admission ceremony and never becomes the thing the edge must verify.

  4. The seam, named: front-channel issuance (Modgud) versus edge verification (Vör); SAML lives entirely on the former and never enters the latter. SLO reuses the session-termination/revocation propagation path (ADR-0016, ADR-0005), not a strong global read.

Consequences

  • The constitution question is settled: SAML does not violate rule 1, because SAML is issuance and session — the side rule 1 does not govern — and it never asks Vör to read the core. The platform gets enterprise SAML SSO without bending the thesis.
  • The seam is verifiable, not asserted. When the SAML IdP is built (a roadmap milestone), the edge-independence property test (ADR-0010) is re-run with SAML in the issuance path; it must still pass with the core unavailable, proving SAML stayed on the issuance side. That re-run is the milestone's definition of done.
  • Token Exchange (ADR-0014) is load-bearing here: reserving it in the v1 surface is what lets SAML bolt on later without re-architecting the edge. This is why ADR-0014 reserves that seat now.
  • XML-DSig and SAML's XML attack surface are confined to one plane (Modgud), keeping that notoriously sharp-edged parsing away from the verification hot path entirely — a security benefit of the placement, not only an architectural one.
  • SAML interoperability conformance is reserved alongside this milestone (ADR-0025), the SAML analog of the OIDC certification target.