Fix AuthSession matching with framework-injected metadata and support actor-based routing

[Copilot]

AuthSessionName-only patterns failed to match when the execution context injected CorrelationId and Actor metadata into the Options parameter. The matching logic treated framework metadata as user-provided options, causing legitimate patterns to be rejected.

Changes

• New-IdleAuthSessionBroker.ps1: Implemented selective framework metadata handling for pattern matching

  • AuthSessionName-only patterns: Framework metadata (CorrelationId, Actor) is ignored during matching
  • Multi-key patterns: All keys including framework metadata participate in matching, enabling actor-based routing
  • Added validation warnings when patterns use framework-controlled keys
  • Framework metadata remains in Options for broker visibility

• New-IdleAuthSession.Tests.ps1: Added comprehensive test coverage for framework metadata scenarios and actor-based routing

• Documentation: Added guidance on framework-reserved keys

  • Updated authentication walkthrough (docs/use/walkthrough/05-providers-authentication.md)
  • Updated cmdlet reference (docs/reference/cmdlets/New-IdleAuthSession.md)
  • Documented behavior and best practices for using CorrelationId and Actor in patterns

Examples

Simple AuthSessionName-only pattern (framework metadata ignored)

Previously failed with "No matching auth session found":

$broker = New-IdleAuthSession -SessionMap @{
    @{ AuthSessionName = 'Entra' } = @{ AuthSessionType = 'OAuth'; Credential = $token }
}

# Framework injects metadata during execution:
# AcquireAuthSession('Entra', @{ CorrelationId = '...'; Actor = '...' })
# Old logic: Pattern has 1 key, Options has 2 keys → no match
# New logic: Pattern has 1 key, framework metadata ignored → match ✓

Actor-based routing with multi-key patterns (framework metadata participates)

$broker = New-IdleAuthSession -SessionMap @{
    @{ AuthSessionName = 'AD'; Actor = 'ops-user' } = $opsCred
    @{ AuthSessionName = 'AD'; Actor = 'admin-user' } = $adminCred
}

# Matches based on Actor value
# AcquireAuthSession('AD', @{ Actor = 'ops-user'; CorrelationId = '...' })
# → Returns $opsCred ✓

User-defined routing options (framework metadata ignored)

@{ AuthSessionName = 'AD'; Role = 'Admin' } 
# Matches when Role='Admin' provided, ignores CorrelationId/Actor

Framework-Reserved Keys

CorrelationId and Actor are automatically injected by the execution framework and have special handling:

• Ignored in AuthSessionName-only patterns to fix the original bug
• Included in multi-key pattern matching to support advanced routing scenarios
• Warning issued when used in patterns to alert users these are framework-controlled

Original prompt

---

This section details on the original issue you should resolve

<issue_title>AuthSession cannot be found also initiated</issue_title>
<issue_description>## Description

An AuthSessionName in Plan invocation cannot be found, although it is clearly initiated.

Name     : Entra - Block account 
Type     : IdLE.Step.DisableIdentity
Status   : Failed
Error    : Exception calling "AcquireAuthSession" with "2" argument(s): "Exception calling "AcquireAuthSession" with "2" argument(s): "No matching auth session found for     
           Name='Entra', Options={ CorrelationId=a9a7d5d0-d40f-4a97-9b5d-48e5b42546b6, Actor=adm-mafl-server } and no default auth session configured.""
Attempts : 1

Steps to Reproduce

0. You need some entraAccess token and AD Credentials first (adCred because for next steps not mentioned below).
1. Workflow definition

@{
    Name           = 'Offboarding Stage 1'
    LifecycleEvent = 'Leaver'

    Steps          = @(
        @{
            Name = 'Entra - Block account'
            Type = 'IdLE.Step.DisableIdentity'
            With = @{
                AuthSessionName = 'Entra'
                IdentityKey = '{{Request.IdentityKeys.sAMAccountName}}@nanotempertech.com'
                Provider = 'Entra'
            }
        }
    )
}

2. Request is

$request = New-IdleRequest -LifecycleEvent 'Leaver' -IdentityKeys @{
    sAMAccountName = 'max.power'
} -DesiredState @{
    OffboardingDate = '2026-02-30'
} -Actor $env:USERNAME 

3. Setting up provider and auth Sessions

$authSessions = New-IdleAuthSession -SessionMap @{
    @{ AuthSessionName = 'AD' }  = @{ AuthSessionType = 'Credential'; Credential = $adCred }
    @{ AuthSessionName = 'Entra' } = @{ AuthSessionType = 'OAuth'; Credential = $entraAccessToken }
    @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth'; Credential = $entraAccessToken }
}

# Creating Providers
$providerAD = New-IdleADIdentityProvider
$providerEntra = New-IdleEntraIDIdentityProvider
$providerEXO = New-IdleExchangeOnlineProvider
$providers = @{
    AD = $providerAD
    Entra = $providerEntra
    EXO = $providerEXO
    AuthSessionBroker = $authSessions
}

4. Plan and Execution
   ``´
   $plan = New-IdlePlan -WorkflowPath $leaverWorkflow -Request $request -Providers $providers
   $result = Invoke-IdlePlan -Plan $plan
   $result.Status
   $$result.Steps | Select-Object Name, Status, StartedUtc, FinishedUtc

## Expected Behavior

Invoke-IdlePlan should find defined AuthSessions.

## Actual Behavior

AuthSession cant be found.
This behavior also remains if only one element is within SessionMap.

## Environment

- PowerShell version: 7.5.4
- OS: Windows Server 2019
- IdLE version / commit: 0.9.5

## Additional Context

Add any other context, logs, or screenshots here.
</issue_description>

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

<comments>
</comments>

• Fixes AuthSession cannot be found also initiated #199

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57a1ca1831

ℹ️ 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".

[Copilot]

Pull request overview

This pull request fixes a critical bug where authentication session matching failed when the execution context injected framework metadata (CorrelationId and Actor) into the Options parameter. The framework automatically adds these metadata keys during execution, but the pattern matching logic was treating them as user-provided options, causing legitimate patterns to be rejected.

Changes:

• Added framework metadata filtering in New-IdleAuthSessionBroker.ps1 to exclude CorrelationId and Actor from pattern matching
• Updated all matching paths (AuthSessionName-based and legacy) to use filtered user options
• Added comprehensive test coverage for framework metadata scenarios

Reviewed changes

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

File	Description
src/IdLE.Core/Public/New-IdleAuthSessionBroker.ps1	Added helper function to filter framework metadata keys from Options before pattern matching; updated all matching logic to use filtered options
tests/Core/New-IdleAuthSession.Tests.ps1	Added new test context with 5 test cases covering framework metadata handling scenarios