IdLE.Provider.AD (On-Prem AD) MVP (Windows-only)

[blindzero]

Goal

• Provide a production-usable on-prem Active Directory provider so IdLE can run real Joiner/Mover/Leaver workflows out of the box.

Scope

• Create new provider module: IdLE.Provider.AD
• Platform support:
  • Windows-only (documented). Requires RSAT / ActiveDirectory module availability on the host.
• Capability naming convention: All capability names MUST be under the IdLE. namespace.
• Capabilities (MVP):
  • IdLE.Identity.Read
  • IdLE.Identity.List (Provider API only, no built-in step)
    • IdLE.Identity.List is exposed as a provider method only (no built-in step in v0.8). Minimal contract: ListIdentities([hashtable] $Filter) returns an array of identity keys (strings). Filtering is optional; providers may support Filter.Search (string prefix match).
  • IdLE.Identity.Create
  • IdLE.Identity.Delete
    • Delete is gated by provider configuration: AD provider advertises IdLE.Identity.Delete only when AllowDelete = $true is set during provider construction. The built-in Delete step MUST declare RequiresCapabilities = @('IdLE.Identity.Delete').
  • IdLE.Identity.Attribute.Ensure ("set")
  • IdLE.Identity.Move (OU/container move)
  • IdLE.Identity.Disable
  • IdLE.Identity.Enable
  • IdLE.Entitlement.* use
    • Entitlement.Kind = 'Group'
    • Entitlement.Id = DistinguishedName (DN) als canonical key
    • Provider MAY accept inputs as SID or sAMAccountName but MUST normalize to DN internally
  • IdLE.Entitlement.List (Groups)
  • IdLE.Entitlement.Grant (Groups)
  • IdLE.Entitlement.Revoke (Groups)
• Identity addressing:
  • Support common identifiers (UPN, sAMAccountName, GUID); document preferred defaults and resolution rules.
  • GUID pattern (^[0-9a-fA-F-]{36}$ or N-format) → resolve by ObjectGuid
  • contains @ → resolve by UPN
  • else → resolve by sAMAccountName
  • On ambiguous match → throw deterministic error (no best-effort)
  • Preferred canonical identity key for outputs: ObjectGuid string (or keep input key; aber festlegen!)
• Idempotency guarantees (required for retries and re-runs):
  • Create: if identity exists, return success with "NoChange"/"AlreadyExists" semantics (no duplicate creation).
  • Delete: if identity is already gone, treat as success ("AlreadyDeleted").
  • Group Grant/Revoke: membership already in desired state must be a no-op success.
  • Move(OU): if already in target OU, no-op success.

Built-in steps (out of the box workflows):

• IdLE.Step.CreateIdentity
  • With: Provider?, IdentityKey, Attributes (hashtable), Enabled?
  • Requires: IdLE.Identity.Create
• IdLE.Step.DisableIdentity
  • With: Provider?, IdentityKey
  • Requires: IdLE.Identity.Disable
• IdLE.Step.EnableIdentity
  • With: Provider?, IdentityKey
  • Requires: IdLE.Identity.Enable
• IdLE.Step.MoveIdentity
  • With: Provider?, IdentityKey, TargetContainer (DN)
  • Requires: IdLE.Identity.Move
• IdLE.Step.DeleteIdentity
  • With: Provider?, IdentityKey
  • Requires: IdLE.Identity.Delete (opt-in gated)

Implementation approach:

• Use a small internal wrapper layer around AD cmdlets so unit tests can mock behavior without requiring a real AD.
  • The AD provider MUST call an internal adapter object only (no direct cmdlet calls outside adapter).
  • Adapter methods (MVP): GetUserByUpn, GetUserBySam, GetUserByGuid, NewUser, SetUser, DisableUser, EnableUser, MoveObject, GetGroupById, AddGroupMember, RemoveGroupMember, GetUserGroups.
  • Unit tests inject a fake adapter implementing the same method names.
• Provider must publish its capability list consistently (capabilities are announced, not assumed).
• Provider contract (capability-driven)
  • Provider MUST implement GetCapabilities() and MUST NOT rely on inference.
  • If provider advertises IdLE.Identity.Create, it MUST implement CreateIdentity(identityKey, attributes) and return { IdentityKey, Changed }.
  • If provider advertises IdLE.Identity.Delete, it MUST implement DeleteIdentity(identityKey) and return { IdentityKey, Changed } with idempotent semantics.
  • If provider advertises IdLE.Identity.Enable, it MUST implement EnableIdentity(identityKey) and return { IdentityKey, Changed }.
  • If provider advertises IdLE.Identity.Move, it MUST implement MoveIdentity(identityKey, targetContainer) and return { IdentityKey, Changed }.
  • If provider advertises IdLE.Identity.Read, it MUST implement GetIdentity(identityKey) returning { IdentityKey, Enabled, Attributes }.
• Authentication model
  • Default: integrated auth (run-as)
  • provider factory accepts -Credential (PSCredential)
  • Provider MUST NOT prompt or start interactive flows
  • Doc: required AD rights for operations

Docs / Examples (part of DoD)

• Document prerequisites (Windows/RSAT/permissions), configuration, and supported identifiers.
• Provide at least one example workflow per LifecycleEvent:
  • Joiner: Create + EnsureAttribute + Group grants + Move to Joiner OU
  • Mover: EnsureAttribute changes + Group delta + optional Move OU
  • Leaver: Disable + Move to Leavers OU + Delete (Delete must require explicit opt-in)
• Integrate with the single demo runner (shared examples script) via -Provider AD.
• All example workflow steps MUST declare RequiresCapabilities to enable plan-time validation and to demonstrate provider capability gating (including Delete opt-in).

Acceptance Criteria

• Provider module loads and advertises capabilities.
• MVP capabilities are implemented and covered by unit tests (mocked; no real AD required).
• Idempotency rules above are enforced and test-covered.
• Example workflows run via the demo runner using -Provider AD (documented commands).