AuthSessionBroker: Make SessionMap optional, implement AuthSessionName routing

[Copilot]

Plan: Make SessionMap optional and implement AuthSessionName-based routing

Understanding Current Behavior

• Explored current AuthSessionBroker implementation
• Reviewed how steps acquire auth sessions via Context.AcquireAuthSession
• Identified that steps only acquire auth sessions when With.AuthSessionName is present
• Found that current routing is Options-only (ignores AuthSessionName parameter)

Implementation Tasks

• Make SessionMap optional in New-IdleAuthSessionBroker
  • Update parameter validation to allow empty/null SessionMap
  • Add validation: require DefaultAuthSession if SessionMap is empty/null
• Implement AuthSessionName-based routing in AcquireAuthSession method
  • Add support for AuthSessionName key in SessionMap keys
  • Implement matching logic: AuthSessionName + Options → AuthSessionName only → Default → Error
  • Add clear error messages for ambiguous matches
  • Prioritize AuthSessionName matches over legacy Options-only matches
• Update steps to use DefaultAuthSession even when AuthSessionName is not set
  • Modify Invoke-IdleProviderMethod to acquire auth session when broker exists (even without AuthSessionName)
  • Make AuthSessionName optional for step ergonomics
• Update wrapper function New-IdleAuthSession to match
• Update tests
  • Add tests for optional SessionMap
  • Add tests for AuthSessionName-based routing
  • Add tests for steps using DefaultAuthSession without AuthSessionName
  • Update existing tests for new behavior
• Run broader test suite to ensure no regressions
• Validate changes with full test suite
• Address PR review comments (round 1)
  • Re-add Server/Domain/Environment examples
  • Clarify DefaultAuthSession requirement
• Address PR review comments (round 2)
  • Fix example consistency (token vs credential type)
  • Add fail-fast when AuthSessionName set without broker
  • Check provider method support before acquiring session
  • Replace magic string 'default' with empty string
  • Improve error handling for broker failures
  • Fix Name-only pattern matching ambiguity

Summary of Changes

Breaking Changes (per agent_instructions):

• SessionMap is now optional in New-IdleAuthSession / New-IdleAuthSessionBroker
• AuthSessionName is now a routing key, not just metadata
• Steps will attempt to acquire default auth sessions even without AuthSessionName
• Name-only SessionMap patterns now only match when Options is null/empty

New Capabilities:

• Single-credential workflows can omit SessionMap entirely
• AuthSessionName-based routing allows intuitive session selection
• Ambiguity detection prevents misconfiguration
• Automatic default session acquisition improves ergonomics
• Better error messages for auth session issues

All tests passing: 381 total tests, 0 failures

Original prompt

---

This section details on the original issue you should resolve

<issue_title>AuthSessionBroker: Make SessionMap optional and implement Name-based routing for AuthSessionName</issue_title>
<issue_description>## Problem Statement

Using authentication sessions with IdLE is currently confusing for users and error-prone in simple scenarios:

• Steps only request an auth session from AuthSessionBroker when With.AuthSessionName is set, effectively making AuthSessionName a hidden trigger rather than a routing key.
• AuthSessionName is not meaningfully mapped to SessionMap entries (routing currently relies on AuthSessionOptions such as Role, if present, or falls back to DefaultAuthSession).
• In common “single credential” scenarios, users should not be forced to define a SessionMap at all; DefaultAuthSession should be sufficient.
• This leads to confusing behavior (e.g., plan execution runs without the intended credential unless AuthSessionName is set) and makes first-time workflows unnecessarily hard.

Goal: Make auth session usage intuitive, deterministic, and ergonomic while remaining backward compatible.

Proposed Solution

1) Make SessionMap optional

Update New-IdleAuthSession / broker configuration so SessionMap can be omitted or empty.

• Allow: -SessionMap $null or no -SessionMap parameter.
• Validation rules:
  • If SessionMap is empty/null and DefaultAuthSession is not set: fail fast with a clear error.
  • If DefaultAuthSession is set: SessionMap is optional.

2) Implement meaningful AuthSessionName routing (AuthSessionName-based mapping)

Extend session mapping keys to support AuthSessionName-based routing and make AuthSessionName a real selector:

• Avoid generic key names like Name in mapping keys; prefer explicit AuthSessionName to reduce ambiguity.

• Allow SessionMap keys to include AuthSessionName and optional selectors (e.g., AuthSessionRole via existing key Role):

  • Example key: @{ AuthSessionName = 'AD'; Role = 'ADAdm' } # Role is the existing key; semantically this is the AuthSessionRole

Matching rules (deterministic):

1. If AuthSessionName and AuthSessionOptions are provided:
   • Match entries where key.AuthSessionName == AuthSessionName and all key/value pairs from AuthSessionOptions match.
2. If only AuthSessionName is provided:
   • Match entries where key.AuthSessionName == AuthSessionName.
   • If multiple matches exist: fail fast with a clear ambiguity error (include which selectors are available).
3. If no match is found:
   • Fall back to DefaultAuthSession if set.
4. If no match and no default:
   • Fail fast with actionable error.

Backward compatibility:

• Existing SessionMap keys that do not include AuthSessionName must continue to work.
• If AuthSessionName is set but mappings are AuthSessionRole-only (legacy keys using only Role), use the existing behavior (Options-only match → default fallback).

3) Improve Step ergonomics (no “hidden trigger”)

Steps should not require With.AuthSessionName merely to use credentials if a broker with a default session exists.

Proposed behavior:

• If a step/provider supports auth sessions and an AuthSessionBroker is available:
  • If With.AuthSessionName is missing but the broker has DefaultAuthSession, the step should still acquire the default session.
  • With.AuthSessionName becomes optional and is only needed for selecting non-default sessions.

4) Documentation + examples

Update documentation to clearly describe:

• When to use DefaultAuthSession vs SessionMap
• How AuthSessionName and AuthSessionOptions are used for routing
• Common patterns:
  • Single credential (no SessionMap)
  • Multiple roles (ADAdm/ADRead)
  • Multiple systems (AD/EXO) + roles

Alternatives Considered

• Keep current behavior and only document the “AuthSessionName as trigger” requirement.

  • Rejected: confusing user experience and easy to misconfigure.

• Make AuthSessionName mandatory everywhere.

  • Rejected: adds unnecessary verbosity and does not solve routing semantics.

• Introduce provider-specific auth routing (per provider).

  • Rejected: should remain a core cross-provider capability.

Impact

• Does this affect existing workflows?

  • Intended to be backward compatible:
    • Existing SessionMap Role-only usage continues to work.
    • Workflows that currently set AuthSessionName keep working.
  • Behavioral improvement: workflows may start using DefaultAuthSession even if AuthSessionName was omitted (desired ergonomic fix).

• Any backward compatibility concerns?

  • Low risk if implemented with conservative matching and clear errors for ambiguous AuthSessionName-only matches.
  • Add unit tests to lock in legacy behavior for Role-only maps.

Additional Context

Example: Single credential (no SessionMap)

$authSession = New-IdleAuthSession -AuthSessionType 'Credential' -De...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes blindzero/IdentityLifecycleEngine#153

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/blindzero/IdentityLifecycleEngine/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 203db12f5c

ℹ️ 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 PR updates IdLE’s authentication session brokering to be more ergonomic and deterministic by allowing workflows to omit SessionMap in single-credential scenarios and by making AuthSessionName a first-class routing key (instead of a hidden trigger).

Changes:

• Make SessionMap optional in New-IdleAuthSession / New-IdleAuthSessionBroker, requiring DefaultAuthSession when SessionMap is null/empty.
• Implement AuthSessionName + AuthSessionOptions routing in AcquireAuthSession, with ambiguity detection and legacy Options-only support.
• Update provider invocation to attempt default auth session acquisition when a broker exists even if With.AuthSessionName is absent, and add/extend tests.

Reviewed changes

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

Show a summary per file

File	Description
tests/Steps/Invoke-IdleStepAuthSession.Tests.ps1	Adds a test asserting default-session acquisition behavior when AuthSessionName is absent.
tests/Core/New-IdleAuthSession.Tests.ps1	Adds test coverage for optional SessionMap and AuthSessionName-based routing/ambiguity handling.
src/IdLE/Public/New-IdleAuthSession.ps1	Makes SessionMap optional in the public wrapper and only forwards it when bound.
src/IdLE.Core/Public/New-IdleAuthSessionBroker.ps1	Makes SessionMap optional; adds AuthSessionName routing, ambiguity detection, and expanded help/examples.
src/IdLE.Core/Public/Invoke-IdleProviderMethod.ps1	Changes auth session acquisition behavior to attempt default session when broker exists.

Comments suppressed due to low confidence (1)

src/IdLE/Public/New-IdleAuthSession.ps1:56

• New-IdleAuthSession now allows omitting SessionMap, but the comment-based help still describes SessionMap as if it were required and doesn’t mention the “DefaultAuthSession required when SessionMap is null/empty” rule. Please update the help text so the public wrapper stays aligned with the core behavior.

        [Parameter()]
        [AllowNull()]
        [AllowEmptyCollection()]
        [hashtable] $SessionMap,

        [Parameter()]
        [AllowNull()]
        [object] $DefaultAuthSession,