govoplan-idm/README.md

# GovOPlaN IDM

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

`govoplan-idm` is the planned integration module for external identity
management systems. It does not own GovOPlaN's internal identity, organization,
account, role, or tenant tables; those remain with `govoplan-identity`,
`govoplan-organizations`, `govoplan-access`, and `govoplan-tenancy`.

The module's purpose is to connect GovOPlaN to upstream identity providers and
directory-management processes without making the platform depend on a single
vendor or protocol.

## Boundary

`govoplan-idm` should own:

- inbound synchronization from external identity-management systems
- identity lifecycle import, update, disable, and reconciliation jobs
- identity-to-organization-function assignment links inside GovOPlaN
- bridge views that combine identity and organization facts, such as identity
  candidates for organization function assignments
- mapping external identities, accounts, groups, organizational units,
  functions, and attributes to GovOPlaN identity, organization, access, and
  tenancy DTOs
- provider-specific connectors for LDAP/AD, SCIM, OIDC profile claims, and
  public-sector directory services once those targets are selected
- dry-run previews, conflict reports, audit events, and rollback metadata for
  identity synchronization

It must not own:

- password authentication, sessions, API keys, or CSRF behavior
- GovOPlaN RBAC permission evaluation
- tenant lifecycle storage
- application-specific authorization rules
- portal citizen identities unless that flow is explicitly delegated to an
  identity-trust or portal module

## Kernel Contract

The module should integrate through kernel capabilities and access-owned public
APIs:

- read/write identities through `govoplan-identity` capability contracts
- resolve organization units and functions through `govoplan-organizations`
- resolve tenants through `govoplan-tenancy`
- hand accepted role/right effects to `govoplan-access`
- emit synchronization and conflict events through the shared event contract
- write audit evidence through the audit sink capability
- expose admin routes through module route contributions
- contribute WebUI admin panels through module UI metadata

No feature module should import IDM internals directly. Feature modules should
ask access, tenancy, or future directory capabilities for normalized identity
facts.

`govoplan-idm` has hard module dependencies on `govoplan-identity` and
`govoplan-organizations`, because its core value is connecting those normalized
facts. Identity remains the owner of identities/accounts. Organizations remains
the owner of units/functions.

## Current Runtime API

The first runtime API exposes identity lookup and organization-function
assignment links:

- `GET /api/v1/idm/settings`
- `PATCH /api/v1/idm/settings`
- `GET /api/v1/idm/organization-identities`
- `GET /api/v1/idm/organization-function-assignments`
- `POST /api/v1/idm/organization-function-assignments`
- `PATCH /api/v1/idm/organization-function-assignments/{assignment_id}`

The candidate endpoint returns searchable identity/account candidates for IDM
assignment forms. Assignment writes validate the identity/account link through
`govoplan-identity` and the function/unit scope through
`govoplan-organizations`. These endpoints exist only when IDM is enabled, which
implies both identity and organizations are enabled through module dependency
planning.

The WebUI exposed by this repository is a normal module UI at `/idm`. It is the
editing surface for identity-to-organization-function assignment links.

## Migration And Permission Transition

The initial IDM migration creates new IDM-owned tables only. No data is migrated
from the legacy access/organization assignment tables.

Canonical permissions for assignment work are:

- `idm:organization_identity:read`
- `idm:organization_assignment:read`
- `idm:organization_assignment:write`
- `idm:settings:read`
- `idm:settings:write`

During the transition, `organizations:function:assign` remains accepted by IDM
assignment and identity-candidate endpoints as a compatibility scope. New role
templates and documentation should use the IDM scopes. Organizations remains the
owner of units and function definitions; IDM owns identity-to-function
assignment links.

`govoplan-access` can consume IDM assignments through the optional
`idm.directory` capability when IDM is installed. This is deliberately optional:
access still works without IDM, and IDM does not require access to store or edit
assignment links. If the audit module is enabled, IDM records assignment and
settings audit events; otherwise the assignment API remains usable without an
audit hard dependency.

An IDM assignment does not grant application permissions by itself. Access grants
role-derived permissions only when an explicit external function role mapping
connects the organization function ID to an assignable role. Those mappings are
managed through the access API at
`/api/v1/admin/external-function-role-mappings`.

Tenant IDM settings can require recorded change requests before assignment
creates or updates are applied. The change-control key is
`idm.organization_assignments`.

Delegated and acting-for assignments are source-specific:

- `delegated` requires a source assignment for the same function, and the
  organization function must allow delegation.
- `acting_for` requires a source assignment for the same function, an
  acting-for account on that source identity, and the organization function must
  allow acting in place.

## First Milestone

The first useful milestone is a read-only synchronization preview:

1. Configure one external directory source.
2. Fetch users/groups/organizational units into a transient snapshot.
3. Map the snapshot to GovOPlaN accounts, users, groups, and tenant bindings.
4. Show creates, updates, disables, conflicts, and skipped records.
5. Emit audit evidence for the preview run.

Applying changes should come later, behind dry-run approval, conflict policy,
rollback metadata, and maintenance-mode safeguards.