SPEC-PWF-FED · v0.1
14 June 2026
Owner: Platform team

Federation

One RiverSync ID behind every app, and the machinery that decides what it can do. This is the manual for the federation sub-hierarchy: four processes that together answer who you are, which apps you may open, which role you hold, and what that role can do — and where. Read this overview for the model, then open the process you need.

1The four processes

One process per document. Sign-in resolves identity into a tenant-scoped, app-gated session; Access provisions people into roles and scopes a partner's cross-tenant view; Roles defines the tenant's role set; Permissions sets what each role can do, and where.

2The six-layer model

The Federation PRD reads authorization as six questions, asked in order. Each layer is owned by one of these four processes — which is exactly how the work divides without overlap: Sign-in resolves the first two, Roles names the vocabulary of the third, Access grants the third and opens the sixth, and Permissions sets the fourth and fifth.

Layer	Question it answers	Owned by	Requirement
1 · Tenant	Which tenant does this account belong to?	Sign-in	ID-1
2 · Entitlement	Which applications can this account open?	Sign-in	AUTH-2
3 · Role	Which role does the account hold in this app?	Roles defines · Access grants	AUTH-1 · FED-6
4 · Permission	What can that role do here?	Permissions	AUTH-3 · FED-9
5 · Scope	Where do those permissions apply?	Permissions	FED-10 · ACC-2
6 · Cross-tenant	What can an outside org see of mine?	Access (partner grants)	PRT-3 · FED-11

The split is also a clean composition (WF-8): Roles creates the role and hands the matrix to Permissions; Access grants a role that already exists and whose powers are already set — it never re-defines either. A change in one layer never silently re-writes another.

3The four processes side by side

Same identity spine, four jobs. Sign-in is the only one that runs for every visitor on every app; the other three are administrative surfaces inside Account.

4Sign-in & session

Federated identity to a tenant-scoped, app-gated session — layers 1 and 2. Full detail is in the sign-in drill-down (SPEC-PWF-AUT).

5Users, roles & partner access

Granting people one role per app, and partners a scoped cross-tenant grant — layers 3 (grant) and 6. Full detail is in the access drill-down (SPEC-PWF-ACS).

6Defining roles

A tenant shapes its own role set — template, per-app reach, the fixed-full Owner — layer 3's vocabulary. Full detail is in the roles drill-down (SPEC-PWF-ROL).

7Permission matrix & scope

What a role can do here, and where — the role × permission matrix with scope overrides that narrow, never widen — layers 4 and 5. Full detail is in the permissions drill-down (SPEC-PWF-PRM).

8Rules in play

The WF-rules that bind the federation processes — the master holds the full set. Note WF-4: lanes are authorization, not decoration — a customer lane never performs a RiverSync-only step.

9Traceability & open questions

What each process realizes and the events it rides; no step stands without evidence (WF-2).

Process	Realizes	Rides events
Sign-in & session	ID-1…3 · AUTH-1 · AUTH-2 · ACC-5 · ADM-5	— (sessions are runtime, ID-4)
Users, roles & partner access	ACC-2 · AUTH-1 · AUTH-4 · PRT-1 · PRT-3 · PRT-5	user.invited · user.role-changed · partner-link.lapsed
Defining roles	FED-6 · FED-7 · FED-8 ⚠ · AUTH-1	— (role-set edits are internal)
Permission matrix & scope	FED-9 · FED-10 · AUTH-3 · ACC-2	— (matrix edits are internal)

• ⚠ FED-8 — partner fixed-full role. Customer tenants fix Owner and riversync fixes admin, but the partner default set ships without a named Owner (Federation PRD §11) — to be resolved before this set leaves draft.
• ⚠ Partners catalog — the Partners-app permission catalog is not yet drafted (Federation PRD §11); the Permissions matrix is incomplete for partner tenants until it lands.
• ⚠ ID-4 — sessions are runtime by design. Sign-in produces no persisted entity; the token is the artefact.

10Revision history

Version	Date	Changes
0.1	14 Jun 2026	First draft — Federation becomes a sub-hierarchy of the workflow set (SPEC-PWF-FED). Gathers the existing sign-in (SPEC-PWF-AUT) and access (SPEC-PWF-ACS) workflows and adds two new ones split from the access model — defining roles (SPEC-PWF-ROL) and permission matrix & scope (SPEC-PWF-PRM) — under workflow/federation/. Maps the four to the Federation PRD's six-layer model. FED-* ids now route to the Federation PRD in cross-references.