govoplan-access/docs/IDENTITY_ACCOUNT_FUNCTION_MODEL.md

# Identity, Account, Function, Role, And Right Model

GovOPlaN access distinguishes identity facts, organizational responsibility,
and authorization decisions. This is groundwork for postboxes, workflows,
service directories, portals, delegation, and audit review.

Directory services, identity providers, and IDM systems can authenticate people
and provide external facts. GovOPlaN access owns the normalized runtime
projection used for sessions, tenant memberships, groups, functions, roles,
delegations, and permission decisions.

## Semantic Layers

- Identity: the real person, service, or external subject. An identity can have
  multiple accounts, for example a normal account and a privileged
  administration account.
- Account: the login or technical account used to authenticate. Access
  decisions are account-based because the account is the acting credential.
- Tenant membership: the account's participation in a tenant.
- Organization unit: the administrative unit where responsibility applies.
  Organization units are hierarchical; access must know when a function applies
  only to one unit or to that unit and all subunits.
- Function: a named responsibility held by an account in an organization unit,
  such as case clerk, intake desk, treasurer, dean's office assistant, or
  committee secretary. A function can map to one or more access roles.
- Role: a permission bundle or workflow authority attached to a function,
  group, or explicit assignment.
- Right: the concrete scope or action permission evaluated at runtime.

The UI and API must not collapse these layers into a generic group concept.
Directory groups can feed mappings, but they must not silently become business
authority without a governed mapping rule.

## Organizational Function Scope

A function is meaningful only with organizational scope. The stable contract
therefore separates:

- `FunctionRef`: the organization-bound function definition, including tenant,
  organization unit, role mappings, and delegation policy flags.
- `FunctionAssignmentRef`: the account-held assignment for that function,
  including identity provenance and whether the assignment applies to all
  subunits of the function's organization unit.

The assignment is the runtime authority. A role mapped to a function does not
grant rights until an account has an active assignment for that function.

Example:

- Identity `Anna Becker` owns accounts `anna` and `anna-admin`.
- Account `anna` has function `Registry Clerk` in organization unit
  `Student Registry`.
- The assignment has `applies_to_subunits = true`, so the same function applies
  to subordinate registry offices unless policy narrows it.
- The function maps to role `registry.case_editor`, which grants rights such as
  `cases:case:update`.

## Delegation And Acting In Place

Functions can be delegated only if the function policy permits it. GovOPlaN
distinguishes two delegation modes:

- Delegation: the delegate acts as themself, with provenance showing the
  delegated function assignment.
- Acting in place: the actor performs an action in another holder's function
  context. Audit and explain responses must show both the real actor account
  and the account being represented.

Both modes should be time-bound, revocable, auditable, and visible in access
explain output. Module code must not infer delegation from ordinary group
membership.

## IDM Boundary

`govoplan-idm` owns synchronization with external IDM systems: SCIM, LDAP,
SAML/OIDC claims, directory attributes, preview, rollback, and mapping import.
It does not own GovOPlaN's internal identity, organization, function, role, or
permission evaluation tables.

`govoplan-identity` owns canonical identity records and identity/account links.
`govoplan-organizations` owns canonical organization units, functions, and
function assignments. During the transition, access keeps a security projection
of those concepts for compatibility and authorization, but new integrations
should target the identity and organization capabilities first.

`govoplan-access` owns the platform projection created from those mappings:

- accounts and tenant membership projection
- identity-to-account links used for explainability
- groups, roles, function assignments, and delegation facts
- permission decisions and explain responses
- access-owned identity and membership change events
- mapping effects after an IDM import is accepted

Access does not own:

- mailboxes, calendars, files, cases, tasks, postboxes, or other module data
- canonical organization structure once `govoplan-organizations` is enabled
- canonical identity records once `govoplan-identity` is enabled
- module-specific ACL records beyond stable principal/group/role references
- external provider internals except where they mutate access-owned state

## Kernel Contracts

The stable DTO and protocol surface lives in
`govoplan_core.core.access`. The current groundwork adds:

- `IdentityRef`
- `OrganizationUnitRef`
- `FunctionRef`
- `FunctionAssignmentRef`
- `FunctionDelegationRef`
- `AccessDecisionProvenance`
- `AccessSemanticDirectory`
- `AccessExplanationService`

Feature modules should consume those contracts instead of importing access ORM
models. Storage, migration, and admin UI work can evolve behind the contract
without changing module integrations.

## Required Explainability

Access decisions must be explainable in concrete terms:

- actor identity and account
- tenant membership
- organization unit
- function assignment or group membership
- role source
- permission or right checked
- delegation or acting-in-place context
- policy, lock, or maintenance state that changed the result

This shape is required for role-bound postboxes, workflow authorization,
service directory personalization, delegated administration, and audit review.

## Consumer Expectations

- Postbox can grant access to a role-bound or function-bound postbox without
  tying the postbox to a specific login account.
- Portal/service directory can show services relevant to a user's current
  organization functions and tenant membership.
- Workflow can ask whether the current account can act in a function context
  for a given organization unit.
- Audit can show who acted, with which account, under which function, and
  whether delegation or acting-in-place was involved.

## Implementation Sequence

Implemented backend foundation:

- Kernel DTOs/protocols are covered by focused contract tests.
- Access-owned storage exists for identities, account links, organization
  units, functions, function-role mappings, function assignments, and function
  delegations.
- Admin APIs exist under `/api/v1/admin/identities`,
  `/api/v1/admin/organization-units`, `/api/v1/admin/functions`,
  `/api/v1/admin/function-assignments`, and
  `/api/v1/admin/function-delegations`.
- `PrincipalRef` population includes identity, role, function assignment, and
  delegation identifiers when those facts exist.
- The access manifest registers `access.semanticDirectory` and
  `access.explanation` capabilities.

Remaining rollout:

1. Move canonical identity and organization reads to `identity.directory` and
   `organizations.directory`, keeping access-owned rows as a compatibility
   projection until migration is complete.
2. Add dedicated WebUI management panels for identities, organization units,
   functions, assignments, and delegations.
3. Add explicit acting-in-place context selection; `act_in_place` delegation
   facts are stored now but do not silently grant permissions without a selected
   acting context.
4. Retrofit postbox, workflow, portal, and audit consumers to use identity,
   organization, and access explanation capabilities rather than local access
   assumptions.