AD Provider: Enforce strict attribute validation with explicit contract

[Copilot]

AD Provider: Attribute Contract and Strict Validation ✅

Implementation Complete

This PR implements strict attribute validation for the AD Provider with fail-fast behavior on unsupported attributes, as specified in the issue.

---

What Changed

Core Implementation

• Get-IdleADAttributeContract.ps1: Defines supported attribute contracts for CreateIdentity (16 attributes + OtherAttributes) and EnsureAttribute (9 attributes)
• Test-IdleADAttributeContract.ps1: Strict validation that throws immediately on unsupported attributes with clear, actionable error messages (now dynamically generated from contract)
• New-IdleADAdapter.ps1: Added OtherAttributes support - passes custom LDAP attributes directly to New-ADUser -OtherAttributes
• New-IdleADIdentityProvider.ps1:
  • CreateIdentity validates all attributes before execution
  • EnsureAttribute validates attribute name before execution and resolves Manager values (DN/GUID/UPN/sAMAccountName)
  • Both emit observability events

Testing

• 10 new validation tests + 2 new Manager resolution tests in ADIdentityProvider.Tests.ps1 (87 total AD provider tests, all passing)
• Updated contract test to use 'Description' instead of generic 'contractKey'
• Complete test coverage of Manager resolution in both CreateIdentity and EnsureAttribute

Documentation

• provider-ad.md: Comprehensive attribute contract section with all attributes documented
• ad-joiner-complete.psd1: Updated example demonstrating OtherAttributes usage
• Clarified OtherAttributes validation: Runtime validation by AD cmdlets, not pre-validated

---

Code Review Feedback Addressed

1. ✅ Dynamic error messages: Error messages now generated from contract, not hard-coded
2. ✅ Event accuracy: Renamed event to AttributesRequested and removed misleading Applied field
3. ✅ Manager resolution: Added Manager resolution (DN/GUID/UPN/sAMAccountName → DN) in EnsureAttribute
4. ✅ Documentation accuracy: Updated OtherAttributes docs to reflect runtime validation
5. ✅ Manager docs verified: Documentation correctly states Manager auto-resolution for EnsureAttribute

---

Key Features

✅ Strict validation by default - Unsupported attributes cause immediate errors (no lenient mode)
✅ Clear error messages - Dynamic list of supported attributes from contract
✅ OtherAttributes support - Custom LDAP attributes can be set via hashtable in CreateIdentity
✅ Manager auto-resolution - Works in both CreateIdentity and EnsureAttribute (DN/GUID/UPN/sAMAccountName)
✅ Observability events - Tracks requested attributes
✅ No backward compatibility - Clean implementation for pre-1.0

---

Test Results

Tests Passed: 87 AD provider tests (all passing), 496 total repo tests
PSScriptAnalyzer: No issues

Original prompt

---

This section details on the original issue you should resolve

<issue_title>AD Provider: Define supported attributes (CreateIdentity vs EnsureAttribute) and enforce strict validation</issue_title>
<issue_description>## Summary

Define and document the supported attribute contract for the AD provider, split by operation:

• CreateIdentity (internally New-ADUser)
• EnsureAttribute (internally Set-ADUser / -Replace / dedicated parameters)

Then enforce strict fail-fast validation so unsupported/unknown attributes cannot be silently ignored.

This addresses the current situation where attributes provided in workflows may not be applied (because the provider adapter maps only a subset of keys), yet execution appears successful.

Motivation

Current behavior (problem)

• In IdLE.Provider.AD, user creation builds a parameter hashtable for New-ADUser from a hard-coded mapping list.
• Attribute keys outside that mapping are simply not passed to New-ADUser and are therefore silently ignored.
• Operators cannot easily see which attributes were actually applied, which violates IdLE’s fail-fast principle.

Additionally, AD cmdlet support differs between:

• New-ADUser supported parameters
• Set-ADUser supported parameters
• Generic LDAP attribute updates via -Add/-Replace/-Clear

So we need an explicit contract to avoid surprise behavior and inconsistencies between steps.

Goals

1. Define an explicit supported attribute contract for:
   • Create: attribute keys supported during CreateIdentity
   • Ensure: attribute keys supported during EnsureAttribute
2. Fail fast by default:
   • Unknown keys must cause a clear error before execution.
3. Observability:
   • Emit events/results describing which attributes were applied (and, if lenient mode exists, which were ignored).
4. Documentation-first:
   • Document the contract in one canonical place and reference it elsewhere.

Non-Goals

• Implementing special handling for Manager resolution/format across steps (tracked in a dedicated issue).
• Providing automatic fallback behavior that tries to guess intent for unknown keys.

Proposed Design

1) Attribute contract definition

Introduce two allowlists (per provider):

• AD.CreateIdentity.SupportedAttributes
• AD.EnsureAttribute.SupportedAttributes

Each list contains the workflow-facing attribute keys that IdLE accepts.

For each supported key, define:

• The underlying AD cmdlet parameter (if applicable), or
• The LDAP attribute name for -Replace/-Add usage, and
• Any value constraints (string, bool, array, DN, etc.)

2) Strict validation (default)

During planning/execution, validate provided attribute keys:

• CreateIdentity: validate With.Attributes keys against AD.CreateIdentity.SupportedAttributes plus the reserved container OtherAttributes.
• EnsureAttribute: validate the requested attribute key(s) against AD.EnsureAttribute.SupportedAttributes.

If unsupported keys are present:

• Throw an exception listing all unsupported keys.
• Provide guidance:
  • “Use OtherAttributes (CreateIdentity only)”
  • “Use dedicated step / upcoming Manager handling”
  • Link to the provider docs section.

3) Optional lenient mode (temporary)

Provide a provider option (default strict):

• AttributeValidationMode = 'Strict' | 'Lenient'
• Default: Strict

In Lenient:

• Keep executing but emit a warning event listing ignored keys.
• Record ignored keys in the provider result.

This is an escape hatch for existing workflows and should be documented as deprecated once adoption is complete.

4) Observability

Emit events during execution:

• Provider.AD.CreateIdentity.AttributesApplied
• Provider.AD.EnsureAttribute.AttributesApplied

Payload (example):

• Requested: list of keys
• Applied: list of keys
• Ignored: list of keys (strict: empty)

OtherAttributes (CreateIdentity only)

CreateIdentity supports a dedicated container:

With = @{
  Attributes = @{
    GivenName       = 'Bar'
    Surname         = 'Foo'
    OtherAttributes = @{
      extensionAttribute1 = 'X'
      employeeType        = 'Contractor'
    }
  }
}

• OtherAttributes must be a hashtable.
• Values must be string/array-of-string compatible with AD cmdlets.
• Keys must be LDAP attribute names.

(Implementation details are covered in this issue only as part of contract + validation. The actual pass-through to New-ADUser -OtherAttributes must be included in this work if not already implemented.)

Implementation Notes (current code locations)

• Provider:
  • src/IdLE.Provider.AD/Public/New-IdleADIdentityProvider.ps1 (CreateIdentity, EnsureAttribute)
• Adapter mapping:
  • src/IdLE.Provider.AD/Private/New-IdleADAdapter.ps1 (NewUser, SetUser)

Acceptance Criteria

1. Contract exists
   • A documented list of supported attributes for CreateIdentity and EnsureAttribute is present in AD provider docs.
   • ...

• Fixes AD Provider: Define supported attributes (CreateIdentity vs EnsureAttribute) and enforce strict validation #164

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR adds an explicit attribute allowlist (“contract”) for the AD identity provider and enforces strict, fail-fast validation so unsupported workflow attributes can’t be silently ignored.

Changes:

• Introduces Get-IdleADAttributeContract + Test-IdleADAttributeContract and integrates validation into CreateIdentity/EnsureAttribute.
• Adds OtherAttributes pass-through support to the AD adapter for custom LDAP attributes during CreateIdentity.
• Updates tests, example workflow template, and AD provider documentation to reflect the new contract and strict behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Providers/ADIdentityProvider.Tests.ps1	Adds strict-mode validation tests for supported/unsupported attributes and OtherAttributes typing.
tests/ProviderContracts/IdentityProvider.Contract.ps1	Updates contract test to use a realistic attribute name for EnsureAttribute.
src/IdLE.Provider.AD/Public/New-IdleADIdentityProvider.ps1	Runs attribute-contract validation before adapter calls; emits new observability events.
src/IdLE.Provider.AD/Private/Test-IdleADAttributeContract.ps1	Implements strict validation + actionable error messages for unsupported attributes.
src/IdLE.Provider.AD/Private/Get-IdleADAttributeContract.ps1	Defines the per-operation supported attribute allowlists.
src/IdLE.Provider.AD/Private/New-IdleADAdapter.ps1	Passes OtherAttributes through to New-ADUser parameters when present.
examples/workflows/templates/ad-joiner-complete.psd1	Demonstrates OtherAttributes usage in the AD joiner workflow template.
docs/reference/providers/provider-ad.md	Documents the attribute contracts, strict validation behavior, and new provider-emitted events.