# 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
- 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.

## 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.