AuthSessionBroker: Support per-entry AuthSessionType in SessionMap

[blindzero]

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 -AuthSessionType omitted:
    • untyped values are rejected
    • typed values work

Alternatives Considered

1. Multiple brokers (one per type)

   • Not supported by current Context.AcquireAuthSession contract (single Providers.AuthSessionBroker).
   • Would complicate host + engine contracts, and make workflows harder to operate.

2. Encode type in AuthSessionName

   • Works as a naming convention but is not enforceable/validatable and increases ambiguity.
   • Does not help with actual validation/lifecycle management.

3. Extend AcquireAuthSession signature to include Type

   • Would be a breaking change across steps/providers/hosts.
   • Not required if the broker can infer type from the matching entry.

Impact

• Backward compatibility: intended to be compatible for existing hosts that pass -AuthSessionType and untyped SessionMap values.
• Workflow impact: none (workflows remain data-only; no schema change required).
• Provider impact: none if AcquireAuthSession continues to return the same session object.
• Core impact: small. Primary changes in New-IdleAuthSessionBroker; optionally add a small private helper for validation.

Additional Context

Relevant current behavior:

• New-IdleAuthSessionBroker stores a single AuthSessionType and has a TODO stating current implementation allows all options for all session types, implying planned type-specific behavior is currently blocked.

Acceptance Criteria (Definition of Done):

• Mixed session types supported in a single broker via typed SessionMap values
• -AuthSessionType optional and acts as default when present
• Clear, actionable errors on type mismatch
• Pester tests added/updated to cover the above
• Documentation and at least one example updated/added to demonstrate mixed types