docs: define governed function assignment workflows

2026-07-31 15:07:53 +02:00
parent ebb3b82cf8
commit d1c5738ca8
2 changed files with 116 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Function Assignment Request And Grant Workflows
+
+## Purpose
+
+Assigning an identity to an organization function is a governed business
+change, not just an IDM table edit. IDM owns the request or grant record and the
+resulting effective-dated assignment. Organizations owns units and function
+definitions. Policy resolves who may initiate, clear, accept, reject, revoke,
+or recover a change. Workflow Engine runs the selected, version-pinned process.
+
+An assignment workflow never grants generic application permissions by itself.
+Access may project an accepted function assignment into roles only through an
+explicit function mapping.
+
+## Two User Journeys
+
+### Request A Function
+
+An eligible user finds a function, sees whether it can be requested and why,
+provides the required justification/evidence, and submits a request. The
+effective policy determines whether the request goes to a current holder, a
+clearing authority, both in sequence, or is unavailable because only an
+authority may initiate the assignment.
+
+The requester can inspect progress, respond to questions, withdraw while
+permitted, and receive the final decision. No effective assignment exists until
+all required approvals and any configured recipient acceptance are complete.
+
+### Bestow A Function
+
+An effective function holder or authority selects an eligible identity and
+proposes a function assignment with scope, validity, delegation, and evidence.
+The policy determines whether the holder may complete the grant, whether an
+authority must clear it, or whether only the authority can initiate and grant
+it. Recipient acceptance can be required or waived only by an explicit policy
+with recorded provenance.
+
+## Grant Profiles
+
+The first policy profiles are:
+
+- `holder_grant`: an effective holder may initiate and approve within the
+  configured scope and duration ceilings.
+- `holder_with_authority_clearance`: a holder or eligible requester may
+  initiate, but the configured authority must clear the change.
+- `authority_only`: only the configured authority may initiate and approve;
+  other users receive an unavailable action with an explanation.
+
+Profiles may additionally configure self-request eligibility, recipient
+acceptance, evidence requirements, separation of duties, quorum, expiry,
+maximum validity, delegation limits, vacancy routing, and escalation. Function
+or function-type configuration references a profile; Policy produces the
+effective decision and provenance rather than IDM duplicating policy logic.
+
+## IDM Aggregate
+
+IDM should persist one function-assignment change aggregate for both journeys:
+
+- change ID, tenant, kind (`request` or `grant`), function, unit, candidate
+  identity/account, requested validity, and assignment source
+- initiator, represented actor/function where applicable, policy profile and
+  decision revision
+- pinned workflow definition/revision and workflow instance reference
+- justification, evidence references, comments, and redacted process variables
+- state and append-only state history
+- resulting assignment ID, or rejection/withdrawal/expiry reason
+- idempotency key and optimistic-concurrency revision
+
+Candidate states are `draft`, `submitted`, `awaiting_holder`,
+`awaiting_authority`, `awaiting_recipient`, `approved`, `accepted`, `applied`,
+`rejected`, `withdrawn`, `expired`, `cancelled`, and `failed_manual_review`.
+Not every profile uses every state.
+
+The workflow instance coordinates the process, but the IDM change record is the
+business source of truth. A workflow callback applies the assignment exactly
+once after successful completion. Failed or outcome-unknown application is
+reconciled without starting a second grant.
+
+## Required Guarantees
+
+- Every action rechecks current identity, holder, authority, function, and
+  Policy facts. Authorization captured at submission is evidence, not a future
+  permission grant.
+- A holder who loses the source function cannot approve later unless Policy
+  explicitly permits continuity for an already-open case.
+- Vacancy and unavailable authority routes produce a visible blocked/escalated
+  state rather than silently granting or losing the request.
+- The proposer and required clearer cannot be the same actor where separation
+  of duties applies.
+- Effective dates, revocation, expiry, delegation, and acting-for semantics use
+  the canonical IDM assignment contract.
+- Notifications are emitted for durable waiting states and final outcomes when
+  Notifications is installed.
+- Audit receives non-secret evidence for every transition when Audit is
+  installed.
+- The direct administrative write path is either disabled for governed
+  functions or treated as an explicit emergency override with reason,
+  provenance, and equivalent evidence.
+
+## Module Boundaries
+
+- Organizations: function definitions and assignment-policy profile reference.
+- IDM: request/grant aggregate, candidate validation, effective assignment, and
+  assignment lifecycle.
+- Policy: effective initiator/approver/acceptance/quorum/expiry decisions and
+  explanations.
+- Workflow Engine: versioned definition installation and process execution.
+- Workflow: optional authoring, inspection, and override UI.
+- Notifications: waiting-state and outcome notifications.
+- Audit: immutable transition and assignment evidence.
+- Access: optional projection of accepted function facts into roles/rights.