AuthSessionBroker: Make SessionMap optional and implement Name-based routing for AuthSessionName

[blindzero]

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' -DefaultAuthSession $admAD

Workflow step (no auth fields required):

With = @{
  IdentityKey = 'foo.bar'
  Attributes  = @{ Path = 'OU=...' }
}

Example: AuthSessionName + AuthSessionRole routing

$authSession = New-IdleAuthSession -AuthSessionType 'Credential' -DefaultAuthSession $defaultCred -SessionMap @{
  @{ AuthSessionName = 'AD';  Role = 'ADAdm' } = $admAD
  @{ AuthSessionName = 'EXO'; Role = 'EXOAdm' } = $exoAdm
}

Workflow:

With = @{
  AuthSessionName    = 'AD'
  AuthSessionOptions = @{ Role = 'ADAdm' }
}

Acceptance Criteria

• SessionMap is optional when DefaultAuthSession is provided; clear error when neither is available.
• AuthSessionName-based routing works:
  • Exact match: AuthSessionName + AuthSessionOptions
  • AuthSessionName-only match (unique) works; ambiguity produces a clear error.
• Steps use DefaultAuthSession even when AuthSessionName is not set (when broker is present).
• Backward compatibility tests for Role-only maps.
• Documentation updated with patterns and examples.