Fix EnsureAttributes null handling and expand AD attribute contract to full Set-ADUser parameter set

[Copilot]

• Create Get-IdleADAttributeLDAPField.ps1 - new function mapping friendly attribute names to verified LDAP field names
• Update Get-IdleADAttributeContract.ps1 - entries define Target/Type/Required only; LDAP field enrichment loop removed; docs updated
• Update New-IdleADAdapter.ps1 - SetUser uses Get-IdleADAttributeContract to detect named parameters, then calls Get-IdleADAttributeLDAPField directly; custom LDAP attrs use -Clear/-Replace
• Update Test-IdleADAttributeContract.ps1 - rename operation; allow OtherAttributes; update error messages
• Update New-IdleADIdentityProvider.ps1 - EnsureAttribute: handles OtherAttributes; throws when OtherAttributes value is not a hashtable (matches CreateIdentity strictness); fixes null comparison; passes $CurrentValue
• Update Invoke-IdleStepEnsureAttributes.ps1 - fix null value preservation
• Update ADIdentityProvider.Tests.ps1 - tests for null clearing, new attributes, OtherAttributes; type-validation test for non-hashtable OtherAttributes in EnsureAttribute
• Update provider-ad.md - OtherAttributes guidance; attribute table removed
• All 101 tests pass

Original prompt

---

This section details on the original issue you should resolve

<issue_title>EnsureAttributes with Provider.AD does not allow to unset attributes</issue_title>
<issue_description>## Description

If attributes are only unset with EnsureAttributes on Provider.AD (maybe others as well?) you'll receive an error about method $null

Steps to Reproduce

1. Create Step with

@{
            Name = 'AD - Remove phone number attributes'
            Type = 'IdLE.Step.EnsureAttributes'
            With = @{
                AuthSessionName = 'AD'
                IdentityKey = '{{Request.IdentityKeys.sAMAccountName}}'
                Provider = 'AD'
                Attributes = @{
                    mobile = $null
                    telephoneNumber = $null
                }
            }
        }

2. Plan + Execute
3. Get Error

Expected Behavior

Attributes are set to $null

Actual Behavior

Error

Cannot bind argument to parameter 'MethodArguments' because it is null.

Environment

• PowerShell version: 7.5.4
• OS: Windows Server 2019
• IdLE version / commit: main branch

Additional Context

Not sure what is breaking it here. It seems that the defined supported / unsupported Attributes of EnsureAttributes is somehow in the way as well. Althought the error message with using

telephoneNumber = '' references to the old EnsureAttribute and not to the new plural one.
Also it refers to "CreateIdentity" not to "EnsureAttributes", what we use here?

Exception calling "EnsureAttribute" with "4" argument(s): "AD Provider: Unsupported attribute in EnsureAttribute operation. 
               Attribute: OtherAttributes

               Supported attributes for EnsureAttribute:
                 - Department
                 - Description
                 - DisplayName
                 - EmailAddress 
                 - GivenName 
                 - Manager
                 - Surname
                 - Title
                 - UserPrincipalName

               Note: Custom LDAP attributes and password attributes are not supported in EnsureAttribute. 
               For custom attributes, use CreateIdentity with OtherAttributes."

We need to find a clear pathway for attribute handling for CreateIdentity Attributes and EnsureAttributes Attributes. They seem to use in AD different set of supported attributes that can be set directly as -AttributeName parameter and via -OtherAttributes for New-ADUser, while Set-ADUser doesn't have this, but -Add, -Replace and -Remove parameters.

But basic conclusion is:

• any string for attributes in EnsureAttributes (with supported parameter in Set-ADUser, but not in list of supported attributes from CreateIdentity) leads to an error on supported attributes
• OtherAttributes, although pointed out also dont work and gives same error
• any $null value on any value to unset a value results in MethodArguments error</issue_description>

<agent_instructions>Make sure that "Get-IdleADAttributeContract" supports the full list of attributes of the corresponding cmdlets (Set-ADUser for EnsureAttributes and New-ADUser for CreateIdentity).
Do not change the format of the return pattern in "Get-IdleADAttributeContract", but add the "required" to EnsureAttributes as well. Keep the grouping with comments.
Also add the LDAP field Name for the attributes. Extract the definiiton of LDAP field names for attributes into a separate function / file so it can be used by multiple different separated parts (e.g. Get-IdLEADAttributeLDAPField or better name). Make sure to verify the LDAP field names by Windows AD Server LDAP schema documentation, do not do assumptions or guesses.

Make sure that documentation of EnsureAttributes and CreateIdentity for AD provider documents that OtherAttributes keys must be correct LDAP names.

Make also sure that the "GetUserBy..." methods of AD Provider Adapter select all properties to enable full comparison with existing values.

Then enable $null Values in EnsureAttributes Step.

With the LDAP fields available you can change the behavior of SetUser method in the AD Adapter to generalized use of -Clear or -Replace or -Add Parameter, depending on if a current value is set or not.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes EnsureAttributes with Provider.AD does not allow to unset attributes #202

---

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

[Copilot]

Pull request overview

This PR fixes null value handling and expands AD attribute contract to support the full Set-ADUser parameter set for EnsureAttributes operations. The changes address issue #202 which reported that EnsureAttributes with Provider.AD did not allow unsetting attributes.

Changes:

• Created Get-IdleADAttributeLDAPField.ps1 for LDAP field name mapping, separating concerns between contract definition and LDAP schema names
• Expanded Get-IdleADAttributeContract.ps1 to include all Set-ADUser parameters for EnsureAttributes (30+ new attributes) and added OtherAttributes container support
• Fixed null value preservation in Invoke-IdleStepEnsureAttributes.ps1 using typed object arrays to prevent PowerShell from dropping null values
• Enhanced New-IdleADIdentityProvider.ps1 EnsureAttribute method with proper null comparison logic and OtherAttributes container handling
• Updated New-IdleADAdapter.ps1 SetUser to use contract-driven parameter detection and LDAP field names for -Clear operations; changed GetUserBy* methods to Properties='*' for full attribute retrieval
• Updated tests and documentation to reflect new functionality

Reviewed changes

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

Show a summary per file

File	Description
src/IdLE.Provider.AD/Private/Get-IdleADAttributeLDAPField.ps1	New function mapping friendly attribute names to LDAP schema field names with RFC/MS-ADSC citations
src/IdLE.Provider.AD/Private/Get-IdleADAttributeContract.ps1	Expanded EnsureAttributes contract to include 30+ Set-ADUser parameters; added OtherAttributes container support
src/IdLE.Provider.AD/Private/Test-IdleADAttributeContract.ps1	Updated operation parameter to EnsureAttributes; added OtherAttributes validation; improved error messages
src/IdLE.Provider.AD/Private/New-IdleADAdapter.ps1	SetUser now uses contract-driven logic to distinguish named parameters from custom LDAP attributes; GetUserBy* methods retrieve all properties
src/IdLE.Provider.AD/Public/New-IdleADIdentityProvider.ps1	EnsureAttribute method handles OtherAttributes container and implements proper null-aware comparison logic
src/IdLE.Steps.Common/Public/Invoke-IdleStepEnsureAttributes.ps1	Fixed null value preservation using typed object arrays for method arguments
tests/Providers/ADIdentityProvider.Tests.ps1	Updated mock SetUser signature; expanded supported attributes list; added tests for null handling and OtherAttributes
docs/reference/providers/provider-ad.md	Added attribute handling section documenting OtherAttributes usage and null clearing for both CreateIdentity and EnsureAttributes

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8652d30791

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".