Support per-entry AuthSessionType in SessionMap with flexible syntax

[Copilot]

Implementation Complete: Per-Entry AuthSessionType with Flexible Syntax

✅ Simple syntax for single auth type + typed syntax for mixed types

Summary

Implemented per-entry AuthSessionType in SessionMap with both simple and typed syntax options.

Changes

1. Flexible Syntax

• Re-added -AuthSessionType parameter (optional)
• Simple syntax (with -AuthSessionType): @{ Role = 'Admin' } = $credential
• Typed syntax (for mixed types): @{ Role = 'Admin' } = @{ AuthSessionType = 'Credential'; Credential = $credential }
• Renamed Session to Credential for better clarity
• Removed PSCustomObject support - only hashtable format supported

2. Testing

• 24 comprehensive tests covering both syntax styles
• Tests for simple syntax with -AuthSessionType
• Tests for typed syntax for mixed types
• Type validation tests
• Routing tests: fallback, ambiguity detection, precedence rules
• All 24 tests pass

3. Validation

• OAuth: Accepts string tokens, PSCredential, objects with AccessToken property, objects with GetAccessToken() method
• PSRemoting: Accepts PSSession, PSCredential, objects with InvokeCommand(CommandName, Parameters) method (DirectorySync pattern)
• Credential: Accepts PSCredential only
• Performance: Validation function cached on broker creation to avoid repeated Get-Command calls

4. Documentation

• Main provider usage docs (docs/use/providers.md) - Complete ✅
• Provider reference docs updated for consistency
  • EntraID provider - removed empty @{}, added Device Code Flow example for MFA scenarios
  • AD provider - already correct
  • EXO provider - no AuthSession examples (uses Connect-ExchangeOnline)
• Simple examples use -AuthSessionType
• Mixed-type example uses typed descriptors
• Clear distinction between simple and advanced usage
• Cmdlet reference will be regenerated by CI

Usage Patterns

Simple (single auth type):

$broker = New-IdleAuthSession -DefaultAuthSession $credential -AuthSessionType 'Credential'

Simple with routing:

$broker = New-IdleAuthSession -SessionMap @{
    @{ Role = 'Tier0' } = $tier0Cred
    @{ Role = 'Admin' } = $adminCred
} -AuthSessionType 'Credential'

Mixed types (typed descriptors):

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

Device Code Flow (MFA-enabled environments):

Import-Module MSAL.PS

$token = Get-MsalToken `
    -ClientId $clientId `
    -TenantId $tenantId `
    -Scopes "https://graph.microsoft.com/.default" `
    -DeviceCode

$broker = New-IdleAuthSession -DefaultAuthSession $token.AccessToken -AuthSessionType 'OAuth'

Quality Assurance

• ✅ All 24 unit tests pass
• ✅ Simpler syntax for common cases
• ✅ Typed syntax for advanced scenarios
• ✅ Clear property name (Credential vs Session)
• ✅ Documentation comprehensively reviewed and updated across all providers
• ✅ Device Code Flow example added for MFA scenarios with MSAL.PS prerequisites
• ✅ Code review feedback addressed
• ✅ DirectorySync provider compatibility maintained
• ✅ Performance optimized (validation function cached)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>AuthSessionBroker: Support per-entry AuthSessionType in SessionMap</issue_title>
<issue_description>## Problem Statement

New-IdleAuthSessionBroker currently requires a single -AuthSessionType value which applies to all sessions returned by the broker.
This is a limitation for realistic workflows where one Providers.AuthSessionBroker must serve multiple providers/systems in a single run.

Example scenarios where a single broker must handle mixed session types:

• Active Directory provider expects a PSCredential (Credential)
• Exchange Online provider expects an OAuth token / connection context (OAuth)
• DirectorySync / Entra Connect steps may require a remoting execution context (PSRemoting)

Today, a SessionMap can technically contain different session value shapes (credential, token, etc.), but AuthSessionType is global and therefore cannot be correct for all entries.
Additionally, the broker has a TODO comment explicitly stating that the current implementation “allows all options for all session types”, so the intended type-specific validation/lifecycle cannot be implemented correctly as long as the type is global.

Goal: enable one AuthSessionBroker instance to route different session types based on AuthSessionName / AuthSessionOptions.

Proposed Solution

1) Extend New-IdleAuthSessionBroker to support per-entry session type

Introduce a typed session descriptor that can be used as the SessionMap value.

New supported value shapes:

• Legacy / unchanged (still supported):
  • @{ ...pattern... } = <any session object>
• New (typed):
  • @{ ...pattern... } = @{ AuthSessionType = 'Credential' | 'OAuth' | 'PSRemoting'; Session = <any> }
  • @{ ...pattern... } = [pscustomobject]@{ AuthSessionType = 'Credential' | 'OAuth' | 'PSRemoting'; Session = <any> }

The broker MUST normalize values internally into a consistent shape like:

• Session (the object that will be returned to the provider)
• AuthSessionType (for validation / telemetry / lifecycle management)

AcquireAuthSession(Name, Options) continues to return only the session object (backward compatible with provider method signatures).
The type is used internally for validation and can optionally be surfaced via events/telemetry if needed.

2) Make -AuthSessionType optional and treat it as default

Change parameter behavior:

• -AuthSessionType becomes optional (but still validated if provided).
• If -AuthSessionType is provided, it acts as DefaultAuthSessionType for:
  • DefaultAuthSession (if set)
  • SessionMap entries that are legacy (untyped) values
• If -AuthSessionType is not provided:
  • every SessionMap entry MUST be typed (new shape), and
  • DefaultAuthSession MUST be typed if present (or explicitly forbidden without a type)

This keeps backward compatibility while enabling mixed-type brokers.

3) Add type-specific validation hooks (minimal now, extensible later)

Implement a small internal validation function:

• Assert-IdleAuthSessionMatchesType -AuthSessionType <type> -Session <object>

Minimal validation (safe defaults, deterministic):

• Credential: allow [pscredential] (and optionally allow SecureString only if explicitly supported elsewhere — default: no)
• OAuth: allow string tokens and/or a known token/container shape (keep minimal and well-defined)
• PSRemoting: allow PSSession, WSManConnectionInfo, or the existing session credential pattern used by the DirectorySync provider

The validation MUST fail fast with an actionable error message, including:

• requested session name
• resolved AuthSessionType
• the actual runtime type of the session object

Note: The validation rules should be introduced in a way that adding new session types later is straightforward (single switch statement / small lookup table).

4) Documentation & Examples

Update docs to reflect:

• Mixed-type broker setup patterns
• Typed SessionMap value schema
• Backward compatible behavior
• Security reminders (no secrets in workflows; broker is host-supplied)

Suggested docs to update:

• Provider auth docs under Use > Providers (AuthSessionBroker section)
• Cmdlet reference help for New-IdleAuthSessionBroker / New-IdleAuthSession wrapper
• Add a concrete example workflow run that uses AD + EXO with a single broker (two different AuthSessionTypes)

5) Tests

Add/extend Pester tests (unit tests, no live calls):

• Backwards compatibility
  • Broker with legacy SessionMap values + -AuthSessionType required behavior should still work
• Mixed types
  • SessionMap with typed values returns correct session per match
  • Mixed types in a single SessionMap are supported
• Validation
  • Wrong type (e.g., AuthSessionType='Credential' but session is token string) fails with clear error
• Default behavior
  • When `-AuthSess...

• Fixes AuthSessionBroker: Support per-entry AuthSessionType in SessionMap #168

---

💡 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.

[blindzero]

@copilot: make sure we do not keep any backward compatibility / legacy stuff in the code or Tests. Only the new way to be supported.

[Copilot]

@copilot: make sure we do not keep any backward compatibility / legacy stuff in the code or Tests. Only the new way to be supported.

Removed all backward compatibility code and tests. Only typed session descriptors are supported now. Changes in commit b783c3f.

[blindzero]

@copilot please review existing examples and Additional docs like providers, quickstart anf so on

[Copilot]

@copilot please review existing examples and Additional docs like providers, quickstart anf so on

Reviewed all documentation and examples. Updated EntraID provider reference to remove deprecated empty @{} patterns and use consistent simple syntax. Changes in commit e59269b.

Review Summary:
✅ docs/use/providers.md - Already updated with all new syntax patterns
✅ docs/reference/providers/provider-ad.md - Already correct (uses simple syntax)
✅ docs/reference/providers/provider-entraID.md - Updated (removed empty @{})
✅ docs/reference/providers/provider-exchangeonline.md - No changes needed
✅ docs/use/quickstart.md - No AuthSession examples
✅ examples/workflows/ - Workflow files are data-only, no broker creation
✅ README.md - No AuthSession examples

All documentation now consistently shows:

• Simple syntax with -AuthSessionType for single auth scenarios
• Typed syntax with Credential property for mixed-type scenarios
• Provider setup with -Providers parameter in all New-IdlePlan examples

[blindzero]

@copilot please also review examples for new authsession behavior and check other provider docu as well (EXO, AD)

[Copilot]

@copilot please also review examples for new authsession behavior and check other provider docu as well (EXO, AD)

Reviewed all provider documentation and examples. Changes in commit a1b4560.

Review Summary:
✅ AD provider - All examples already correct (uses simple syntax with -AuthSessionType)
✅ EXO provider - No AuthSession examples (uses Connect-ExchangeOnline pattern)
✅ EntraID provider - Added Device Code Flow example for MFA scenarios
✅ Examples folder - Workflow files are data-only, no broker creation code
✅ Examples README - No AuthSession examples present

All provider documentation now consistent with simple syntax for single-auth scenarios and typed syntax for mixed-type scenarios.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1b45600db

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

Adds support for per-entry AuthSessionType in SessionMap for IdLE’s AuthSessionBroker, enabling mixed authentication types (e.g., AD credentials + OAuth tokens) within a single broker instance.

Changes:

• Made -AuthSessionType optional and introduced typed session descriptors (@{ AuthSessionType = ...; Credential = ... }) with normalization in New-IdleAuthSessionBroker.
• Added Assert-IdleAuthSessionMatchesType and integrated runtime type validation before returning sessions.
• Updated Pester tests and provider/auth documentation to reflect the new flexible syntax.

Reviewed changes

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

Show a summary per file

File	Description
tests/Core/New-IdleAuthSession.Tests.ps1	Updates tests for simple vs typed syntax and adds basic type-validation assertions.
src/IdLE/Public/New-IdleAuthSession.ps1	Public wrapper: makes -AuthSessionType optional and updates help/examples.
src/IdLE.Core/Public/New-IdleAuthSessionBroker.ps1	Core implementation: normalizes SessionMap/default sessions into typed entries and validates on acquisition.
src/IdLE.Core/Private/Assert-IdleAuthSessionMatchesType.ps1	New validation helper for Credential/OAuth/PSRemoting session shapes.
docs/use/providers.md	Updates usage docs for simple + mixed-type broker patterns; adds examples.
docs/reference/providers/provider-entraID.md	Updates EntraID provider examples, including a device-code flow example.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• www.powershellgallery.com
  • Triggering command: /usr/bin/pwsh pwsh -NoProfile -File ./tools/Generate-IdleCmdletReference.ps1 -InstallPlatyPS (dns block)
  • Triggering command: /usr/bin/pwsh pwsh -NoProfile -Command Install-Module -Name platyPS -Scope CurrentUser -Force; ./tools/Generate-IdleCmdletReference.ps1 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

docs/use/providers.md:160

• This sentence is now inaccurate given the new behavior: when -AuthSessionType is provided, SessionMap/DefaultAuthSession values can be untyped (the broker supplies the default type). Consider rewording to clarify that either the broker has a default AuthSessionType or each entry is a typed descriptor with its own AuthSessionType.

AuthSessionBroker session values must specify an `AuthSessionType` that determines validation rules, lifecycle management, and telemetry behavior:

- **`OAuth`** - Token-based authentication (e.g., Microsoft Graph, Exchange Online)
- **`PSRemoting`** - PowerShell remoting execution context (e.g., Entra Connect)
- **`Credential`** - Credential-based authentication (e.g., Active Directory, mock providers)