Vord

Architecture Decision Record

0019. Upstream identity federation (social and external-IdP login)

Context

Two features that look different to users are the same mechanism underneath: CIAM social login ("continue with Google / Apple / Microsoft") and workforce "bring your own IdP" ("log in with your company's Okta / Entra / SAML IdP"). Both make Vord a relying party to an upstream identity provider, then have Vord mint its own tokens for the downstream relying parties. Recognising these as one capability — Vord-as-RP — avoids building two subsystems, and placing it correctly keeps it on the issuance side of the constitution.

Decision

  1. Upstream federation is an AuthenticationMethod (ADR-0015): one more way to authenticate a principal at Modgud (ADR-0009), in which Modgud acts as an OIDC or SAML client to an external IdP. The external login proves the principal; Modgud then mints Vord's own short-TTL, edge-verifiable token via token exchange (ADR-0014). The external assertion is consumed at the admission plane and never travels to Vör — federation is issuance, and what the edge verifies is always a Vord-issued JOSE token (rule 1).

  2. One mechanism, two products. The same federation method serves CIAM social login and workforce external-IdP login; the difference is realm policy (ADR-0012) — which upstream providers are offered, and whether registration is open (CIAM) or restricted to the federated organisation (workforce).

  3. Just-in-time provisioning on first login writes the core. The first time a federated principal appears, Modgud provisions a Vord principal (ADR-0011), creating the unique (tenant, identifier) index entry — the irreducible core write rule 2 permits — and links the upstream subject to it. Subsequent logins resolve through that link; the upstream subject is one more external identifier on a stable internal id.

  4. Account linking is explicit. Linking a federated identity to an existing principal (same human, second provider) is a deliberate, verified operation, not an implicit email match, to avoid account-takeover by email collision — a CIAM security concern handled at the admission plane.

Consequences

  • Vord covers both the consumer "sign in with…" surface (Auth0 territory) and the enterprise "federate to the customer's IdP" surface (Entra/Okta territory) with one subsystem behind the ADR-0015 method seam.
  • Because federation is issuance and the emitted token is an ordinary Vord JOSE token, the edge path is unchanged and the edge-independence property (ADR-0010) is unaffected — a federated user verifies exactly like a password user.
  • JIT provisioning ties federation to the directory's uniqueness model (ADR-0011), so a federated population scales on the same per-tenant op-rate dimension and the same millions-per-realm target (ADR-0012) as any other.
  • This composes with SAML (ADR-0017): "bring your own SAML IdP" is upstream federation where the upstream protocol is SAML, mirrored by Vord-as-SAML-IdP on the downstream — the same token-exchange seam on both sides.