diff --git a/README.md b/README.md index 9d46480..569a61b 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,11 @@ Delegated and acting-for assignments are source-specific: acting-for account on that source identity, and the organization function must allow acting in place. +Function requests and holder/authority initiated grants require a governed +change record before the effective assignment is created. The target journeys, +grant profiles, state model, and module boundaries are documented in +[Function assignment request and grant workflows](docs/FUNCTION_ASSIGNMENT_WORKFLOWS.md). + ## First Milestone The first useful milestone is a read-only synchronization preview: diff --git a/docs/FUNCTION_ASSIGNMENT_WORKFLOWS.md b/docs/FUNCTION_ASSIGNMENT_WORKFLOWS.md new file mode 100644 index 0000000..912b17a --- /dev/null +++ b/docs/FUNCTION_ASSIGNMENT_WORKFLOWS.md @@ -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.