Add AuthSessionType to standardize authentication session classification

[Copilot]

Implementation Complete ✅

All code review feedback addressed.

✅ Changes Made (Latest Update)

MDX Parsing Fix:

• Fixed MDX parsing error in New-IdleAuthSession.md
• Replaced {{ Fill ProgressAction Description }} placeholder with proper description
• Eliminates DoubleBrace MDX risk error in CI

Cmdlet Reference Documentation:

• Updated New-IdleAuthSession.md to reflect current API:
  • Changed DefaultCredential → DefaultAuthSession
  • Changed type from [PSCredential] → [object]
  • Added mandatory AuthSessionType parameter
  • Updated example to include -AuthSessionType 'Credential'
  • Listed accepted values: OAuth, PSRemoting, Credential
  • Fixed MDX parsing issues

API Enhancement - DefaultAuthSession:

• Renamed parameter: DefaultCredential → DefaultAuthSession for clarity
• Widened type: Changed from [PSCredential] to [object] to support:
  • Token strings for OAuth scenarios (e.g., Microsoft Graph access tokens)
  • Session objects for PSRemoting scenarios (e.g., remote session handles)
  • PSCredential objects for Credential scenarios (Active Directory)
• This eliminates the need to wrap tokens in PSCredential objects

Simplified AuthSessionType values to only meaningful distinctions:

• OAuth - Token-based authentication (token strings or objects can be passed directly)
• PSRemoting - PowerShell remoting execution context (session objects)
• Credential - Credential-based authentication (PSCredential objects, replaces both Implicit and None)

Documentation and Examples:

• Mock provider: Clarified it doesn't require authentication or AuthSessionType
• OAuth examples: Simplified to pass raw tokens directly (no PSCredential wrapping needed)
• All examples: Updated to use DefaultAuthSession parameter and include mandatory AuthSessionType
• Tests: Changed from OAuth to Credential type when using PSCredential objects
• User guide: Fixed leftover "Implicit" reference to "Credential"
• Cmdlet reference: Now up to date with current API and MDX-safe

Updated:

• Core broker API (New-IdleAuthSessionBroker and New-IdleAuthSession)
• All 16 tests (all passing)
• Provider documentation:
  • AD → Credential
  • Mock → Not applicable (doesn't require auth)
  • EntraID, ExchangeOnline → OAuth
  • DirectorySync.EntraConnect → PSRemoting
• User guide examples with direct token usage for OAuth
• Cmdlet reference documentation (MDX-safe)

✅ All 358 tests passing

The API now supports all session types natively without type conversion workarounds. OAuth tokens can be passed directly as strings, PSRemoting session objects work seamlessly, and PSCredential objects continue to work for credential-based scenarios.

Breaking Changes

1. AuthSessionType is now mandatory - all broker creation calls must specify the session type
2. Parameter renamed - DefaultCredential → DefaultAuthSession (though the type change makes this more of a fix than a break)

Both changes are acceptable for pre-1.0 project status and are documented in all examples.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Introduce AuthSessionType to standardize AuthSessionBroker behavior across sessions</issue_title>
<issue_description>## Problem Statement

Providers currently use the Auth/Session broker in different ways (OAuth for Graph/EXO, implicit/no-session patterns for AD, and PSRemoting execution contexts for the Directory Sync / Cloud Sync provider (EntraConnect)).

Without an explicit session classification, it’s harder to:

• validate provider configuration consistently
• manage lifecycle (connect/disconnect, refresh, cleanup)
• implement caching/reuse rules
• emit reliable telemetry/events for diagnostics

We want a consistent mechanism to describe what kind of session the broker is handling.
Target date: 2026-01-31

Proposed Solution

Extend the AuthSessionBroker API and domain model with an explicit AuthSessionType.

Proposed model

• Add AuthSessionType (name is fixed) as a required or strongly-recommended field for session acquisition.
• Typical values (final set can be adjusted):
  • OAuth (Graph, ExchangeOnline)
  • PSRemoting (EntraConnect remote execution)
  • Implicit / None (AD where module/capability exists without explicit session)
  • (optional) LocalElevated if later needed

Behavior

• The broker uses AuthSessionType to:
  • validate required config fields
  • execute type-specific connect/acquire logic
  • determine cleanup rules
  • structure event/log output

Required updates

• Update providers to pass/declare the correct AuthSessionType:
  • IdLE.Provider.EntraID => OAuth
  • IdLE.Provider.ExchangeOnline => OAuth
  • IdLE.Provider.AD => Implicit (or None) unless it has explicit session management
  • IdLE.Provider.DirectorySync.EntraConnect (Directory Sync / Cloud Sync provider) => PSRemoting

Acceptance criteria

• Broker API supports AuthSessionType and validates inputs accordingly.
• All first-party providers compile/run and use the correct AuthSessionType.
• Pester tests cover:
  • validation behavior per AuthSessionType
  • at least one provider per type (OAuth + PSRemoting + Implicit/None)
• Documentation explains how providers should choose AuthSessionType.

Implementation checklist (agent-ready)

• Add AuthSessionType to the relevant domain model(s) / broker request structures
• Add validation rules per type
• Implement type-specific acquisition hooks (even if some are no-ops initially)
• Update providers to specify AuthSessionType
• Add/adjust tests for broker behavior
• Update docs/examples where sessions are configured

Alternatives Considered

• Keep the broker “untyped” and rely on ad-hoc data fields.
  • Rejected: makes validation, lifecycle, reuse and telemetry inconsistent.
• Introduce different broker functions per session kind.
  • Rejected: more API surface and harder to extend; a single typed entry point scales better.

Impact

• Likely a breaking change if AuthSessionType becomes required and existing configs/providers omit it.
  • Since the project is pre-1.0, breaking changes are acceptable but must be documented.
• Provider implementations and tests will need updates.

Additional Context

• This aligns with the architectural principle that the broker handles session lifecycle consistently across providers.
• EntraConnect requires PSRemoting-based execution rather than OAuth, but should still use the same broker pattern.
  </issue_description>

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

• Fixes Introduce AuthSessionType to standardize AuthSessionBroker behavior across sessions #134

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR introduces an AuthSessionType classification to the AuthSession broker API to standardize how different provider authentication patterns (OAuth tokens, PSRemoting contexts, and PSCredential-based auth) are described and validated across IdLE.

Changes:

• Made AuthSessionType a mandatory parameter on New-IdleAuthSession and New-IdleAuthSessionBroker, and exposed it as a broker property.
• Added/updated Pester tests to validate the new parameter and basic acquisition behavior across types.
• Updated provider/user documentation to describe required AuthSessionType per provider and added new usage examples.

Reviewed changes

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

Show a summary per file

File	Description
tests/Core/New-IdleAuthSession.Tests.ps1	Updates existing tests and adds new contexts for AuthSessionType validation and acquisition.
src/IdLE/Public/New-IdleAuthSession.ps1	Public wrapper now requires AuthSessionType and forwards it to Core.
src/IdLE.Core/Public/New-IdleAuthSessionBroker.ps1	Core broker now requires AuthSessionType, stores it on the broker object, and documents intended future validation hooks.
docs/use/providers.md	Adds AuthSessionType documentation and new examples for Credential + OAuth patterns.
docs/reference/providers/provider-mock.md	Documents required AuthSessionType for Mock provider (needs consistency fixes).
docs/reference/providers/provider-exchangeonline.md	Documents required AuthSessionType for ExchangeOnline provider.
docs/reference/providers/provider-entraID.md	Updates examples and documents required AuthSessionType for EntraID provider.
docs/reference/providers/provider-directorysync-entraconnect.md	Documents required AuthSessionType for EntraConnect provider.
docs/reference/providers/provider-ad.md	Documents required AuthSessionType for AD provider and updates examples accordingly.

Comments suppressed due to low confidence (1)

src/IdLE.Core/Public/New-IdleAuthSessionBroker.ps1:47

• The first help example is labeled as an OAuth session type, but it uses $tier0Credential/$adminCredential and New-IdleADIdentityProvider (credential-based). This is misleading given the documented meaning of AuthSessionType. Either switch this example to AuthSessionType 'Credential' (and keep the AD example), or change the example to use OAuth token values + an OAuth-based provider.

    # Simple role-based broker with OAuth session type
    $broker = New-IdleAuthSessionBroker -SessionMap @{
        @{ Role = 'Tier0' } = $tier0Credential
        @{ Role = 'Admin' } = $adminCredential
    } -DefaultCredential $adminCredential -AuthSessionType 'OAuth'

    $plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
        Identity = New-IdleADIdentityProvider
        AuthSessionBroker = $broker

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dd6af4a677

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

[blindzero]

@copilot generate a new cmdlet reference

[Copilot]

@copilot generate a new cmdlet reference

Updated the cmdlet reference documentation manually to reflect the current API signature (DefaultAuthSession with [object] type and mandatory AuthSessionType parameter). Changed in d66aa83.

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 -File ./tools/Generate-IdleCmdletReference.ps1 -InstallPlatyPS (dns block)
  • Triggering command: /usr/bin/pwsh pwsh -Command Register-PSResourceRepository -PSGallery -Trusted -ErrorAction SilentlyContinue; Install-PSResource -Name platyPS -Scope CurrentUser -TrustRepository -Confirm:$false; pwsh -File ./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)

[blindzero]

@copilot

MDX risks (possible accidental MDX parsing)
-------------------------------------------
- docs/reference/cmdlets/New-IdleAuthSession.md:91 [DoubleBrace] {{ Fill ProgressAction Description }}
Error: MDX risk (DoubleBrace): {{ Fill ProgressAction Description }}

cmdlet also

[Copilot]

@copilot

MDX risks (possible accidental MDX parsing)

...

Fixed the MDX parsing error by replacing {{ Fill ProgressAction Description }} with a proper description. Changed in ccb1272.

[blindzero]

@copilot cmdlet reference also needs regeneration

[Copilot]

@copilot cmdlet reference also needs regeneration

The cmdlet reference has been manually updated to match the current API (commit d66aa83) and MDX issues fixed (commit ccb1272). The platyPS generation tool cannot be installed in the CI environment due to network restrictions blocking PowerShellGallery access. All documentation is now accurate and MDX-safe. If regeneration via platyPS is required, it would need to be run locally where network access to PowerShellGallery is available.