164 lines
8.2 KiB
Markdown
164 lines
8.2 KiB
Markdown
# 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.
|
|
|
|
## Delegation, Substitution, And Acting In Place
|
|
|
|
These modes are explicit assignment sources; ordinary group membership never
|
|
creates them:
|
|
|
|
- A **delegated assignment** is a bounded substitution. For example, a registry
|
|
lead may delegate the same delegable function to a deputy until Friday. The
|
|
deputy acts as themself, and Access receives both the derived assignment ID
|
|
and its source assignment ID.
|
|
- An **acting-for assignment** is a bounded representation context. For example,
|
|
an assistant may select an active acting context for the represented function
|
|
holder. Access records the real account, the selected assignment, and the
|
|
represented account on the session and in audit evidence. No acting-for
|
|
authority is effective until that exact context is selected.
|
|
- A **direct assignment** is the holder's own function fact and has no source
|
|
assignment or represented account.
|
|
|
|
The Organizations function must permit the requested mode. The source and
|
|
derived assignments must belong to the same tenant and function, and the
|
|
source must be current and active. An actor also needs the assignment-write
|
|
scope; where a governance profile is enabled, Policy must authorize the
|
|
request/grant or an administrator must use the recorded emergency-override
|
|
path. Validity windows make substitutions expire automatically. Deactivation
|
|
revokes an assignment without deleting its provenance. IDM emits changed,
|
|
revoked, and expired lifecycle events and writes the normal assignment audit
|
|
record; effective-directory reads immediately exclude inactive, future,
|
|
expired, or source-invalid derived assignments.
|
|
|
|
## 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 persists 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`, `changes_requested`, `blocked`,
|
|
`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.
|
|
|
|
## Configuration And Runtime Contract
|
|
|
|
Function settings use `assignment_governance`. Tenant defaults may be supplied
|
|
through `settings.function_assignment_governance_defaults`; function values
|
|
override only the corresponding defaults. Supported keys include
|
|
`request_profile`, `grant_profile`, `authority_function_id`,
|
|
`recipient_acceptance_required`, `evidence_required`,
|
|
`separation_of_duties`, `quorum`, `maximum_validity_days`, and
|
|
`request_expiry_hours`. Missing or malformed profiles fail closed.
|
|
|
|
IDM exposes governed changes at
|
|
`/api/v1/idm/function-assignment-changes`. Mutations require a strong `If-Match`
|
|
precondition and the aggregate revision. Requests and grants pin the exact
|
|
Workflow definition revision and hash, retain append-only transition evidence,
|
|
support review change requests and responses, and apply an assignment exactly
|
|
once. Vacant holder or authority functions create a visible `blocked` state;
|
|
the lifecycle worker expires overdue open changes durably.
|
|
|
|
Direct administration remains available for independently deployed IDM. When
|
|
a function has an enabled governance profile, however, direct create or update
|
|
requires `idm:function_change:admin` plus an emergency override reason. IDM
|
|
stores the actor, time, reason, and evidence references with the assignment and
|
|
includes them in the normal Audit change record.
|
|
|
|
## 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.
|