govoplan-idm/README.md

GovOPlaN IDM

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.