Support per-entry AuthSessionType in SessionMap with flexible syntax

docs/reference/cmdlets/New-IdleAuthSession.md

@@ -13,7 +13,7 @@ Creates a simple AuthSessionBroker for use with IdLE providers.
 ## SYNTAX
 
 ```
-New-IdleAuthSession [[-SessionMap] <Hashtable>] [[-DefaultAuthSession] <Object>] [-AuthSessionType] <String>
+New-IdleAuthSession [[-SessionMap] <Hashtable>] [[-DefaultAuthSession] <Object>] [[-AuthSessionType] <String>]
  [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
@@ -28,9 +28,17 @@ This is a thin wrapper that delegates to IdLE.Core\New-IdleAuthSessionBroker.
 
 ### EXAMPLE 1
 ```
+# Simple broker with single credential
+$broker = New-IdleAuthSession -DefaultAuthSession $credential -AuthSessionType 'Credential'
+```
+
+### EXAMPLE 2
+```
+# Mixed-type broker for AD + EXO
 $broker = New-IdleAuthSession -SessionMap @{
-    @{ Role = 'Tier0' } = $tier0Credential
-} -AuthSessionType 'Credential'
+    @{ AuthSessionName = 'AD' } = @{ AuthSessionType = 'Credential'; Credential = $adCred }
+    @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth'; Credential = $token }
+}
 ```
 
 ## PARAMETERS
@@ -66,9 +74,10 @@ Accept wildcard characters: False
 ```
 
 ### -AuthSessionType
-Specifies the type of authentication session.
-This determines validation rules,
-lifecycle management, and telemetry behavior.
+Optional default authentication session type.
+When provided, allows simple (untyped) 
+session values.
+When not provided, values must be typed descriptors.
 
 Valid values:
 - 'OAuth': Token-based authentication (e.g., Microsoft Graph, Exchange Online)
@@ -80,7 +89,7 @@ Type: String
 Parameter Sets: (All)
 Aliases:
 
-Required: True
+Required: False
 Position: 3
 Default value: None
 Accept pipeline input: False

docs/reference/providers/provider-entraID.md

@@ -1,3 +1,3 @@
 ---
 title: Provider Reference - IdLE.Provider.EntraID
 sidebar_label: Entra ID
@@ -86,10 +86,8 @@
 Connect-AzAccount
 $token = (Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com").Token
 
-# Create broker with OAuth session type (tokens can be passed directly)
-$broker = New-IdleAuthSession -SessionMap @{
-    @{} = $token
-} -DefaultAuthSession $token -AuthSessionType 'OAuth'
+# Create broker with OAuth session type
+$broker = New-IdleAuthSession -DefaultAuthSession $token -AuthSessionType 'OAuth'
 
 # Create provider
 $provider = New-IdleEntraIDIdentityProvider
@@ -112,21 +110,57 @@
 # Obtain token (pseudo-code - use your preferred auth library)
 $token = Get-GraphAppOnlyToken -ClientId $clientId -ClientSecret $clientSecret -TenantId $tenantId
 
-# Create broker with OAuth session type (tokens can be passed directly)
-$broker = New-IdleAuthSession -SessionMap @{
-    @{} = $token
-} -DefaultAuthSession $token -AuthSessionType 'OAuth'
+# Create broker with OAuth session type
+$broker = New-IdleAuthSession -DefaultAuthSession $token -AuthSessionType 'OAuth'
 
 # Rest is identical to delegated flow
 ```
 
+### Example: Device Code Flow (MFA-enabled environments)
+
+For environments requiring MFA, use Device Code Flow with an app registration and MSAL.PS.
+
+**Prerequisites:**
+- Install MSAL.PS module: `Install-Module MSAL.PS -Scope CurrentUser`
+- App registration with delegated permissions (e.g., `User.ReadWrite.All`, `Group.ReadWrite.All`)
+- App must allow public client flows (Authentication > Advanced settings > Allow public client flows: Yes)
+
+```powershell
+# Import MSAL.PS
+Import-Module MSAL.PS
+
+# Obtain token via Device Code Flow
+$clientId = "your-app-id"  # Application (client) ID from app registration
+$tenantId = "your-tenant-id"
+
+$token = Get-MsalToken `
+    -ClientId $clientId `
+    -TenantId $tenantId `
+    -Scopes "https://graph.microsoft.com/.default" `
+    -DeviceCode
+
+# Create broker with OAuth session type
+$broker = New-IdleAuthSession -DefaultAuthSession $token.AccessToken -AuthSessionType 'OAuth'
+
+# Create provider
+$provider = New-IdleEntraIDIdentityProvider
+
+# Use in plan
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
+    Identity = $provider
+    AuthSessionBroker = $broker
+}
+```
+
+The Device Code Flow will display a code and URL for the user to authenticate in a browser, supporting MFA and conditional access policies.
+
 ### Example: Multi-Role Scenario
 
 ```powershell
 $tier0Token = Get-GraphToken -Role 'Tier0'
 $adminToken = Get-GraphToken -Role 'Admin'
 
-# Create broker with OAuth session type (tokens can be passed directly)
+# Create broker with role-based routing
 $broker = New-IdleAuthSession -SessionMap @{
     @{ Role = 'Tier0' } = $tier0Token
     @{ Role = 'Admin' } = $adminToken

docs/use/providers.md

@@ -153,65 +153,141 @@ host-supplied broker. Using the **AuthSessionBroker** is in particular helpful f
 
 ### AuthSessionType
 
-Each `AuthSessionBroker` must specify an `AuthSessionType` that determines validation rules, lifecycle management, and telemetry behavior:
+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)
 
 Each provider documents its required `AuthSessionType` in its reference documentation.
 
-### Example: Active Directory with Credential Auth
+### Example: Simple Single Credential
+
+For the simplest case with just one credential:
+
+```powershell
+# Obtain credential (e.g., from a secure vault or credential manager)
+$credential = Get-Credential -Message "Enter admin credentials"
+
+# Create provider
+$provider = New-IdleADIdentityProvider
+
+# Create broker with single credential
+$broker = New-IdleAuthSession -DefaultAuthSession $credential -AuthSessionType 'Credential'
+
+# Use in plan
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
+    Identity = $provider
+    AuthSessionBroker = $broker
+}
+```
+
+### Example: Role-Based Credentials
+
+For scenarios with multiple credentials for different roles, use `AuthSessionOptions` in workflows to select the appropriate credential:
 
 ```powershell
-# Assuming you have credentials available (e.g., from a secure vault or credential manager)
+# Obtain credentials (e.g., from a secure vault or credential manager)
 $tier0Credential = Get-Credential -Message "Enter Tier0 admin credentials"
 $adminCredential = Get-Credential -Message "Enter regular admin credentials"
 
 # Create provider
 $provider = New-IdleADIdentityProvider
 
-# Create broker with role-based credential mapping and Credential session type
+# Create broker with role-based credential mapping
 $broker = New-IdleAuthSession -SessionMap @{
     @{ Role = 'Tier0' } = $tier0Credential
     @{ Role = 'Admin' } = $adminCredential
 } -DefaultAuthSession $adminCredential -AuthSessionType 'Credential'
 
-# Use provider with broker
+# Use in plan
 $plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
     Identity = $provider
     AuthSessionBroker = $broker
 }
 ```
 
+In the workflow definition, steps specify which role to use via `AuthSessionOptions`:
+
+```powershell
+With = @{
+    ...
+    AuthSessionOptions = @{ Role = 'Tier0' }
+}
+```
+
 ### Example: Entra ID with OAuth
 
 ```powershell
 # Host obtains token (example using Azure PowerShell)
 Connect-AzAccount
 $token = (Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com").Token
 
-# Create broker with OAuth session type (tokens can be passed directly)
-$broker = New-IdleAuthSession -SessionMap @{
-    @{} = $token
-} -DefaultAuthSession $token -AuthSessionType 'OAuth'
-
 # Create provider
 $provider = New-IdleEntraIDIdentityProvider
 
+# Create broker with OAuth session type
+$broker = New-IdleAuthSession -DefaultAuthSession $token -AuthSessionType 'OAuth'
+
 # Use in plan
 $plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
     Identity = $provider
     AuthSessionBroker = $broker
 }
 ```
 
-The different authentication sessions are used by the workflow definition by the steps via `AuthSessionOptions`.
+### Example: Mixed Authentication Types (AD + EXO)
+
+For workflows that need multiple providers with different authentication types:
+
 ```powershell
-With = @{
-    ...
-    AuthSessionName = 'ActiveDirectory'
-    AuthSessionOptions = @{ Role = 'Tier0' }
+# Obtain credentials and tokens
+$adCredential = Get-Credential -Message "Enter AD admin credentials"
+Connect-AzAccount
+$exoToken = (Get-AzAccessToken -ResourceUrl "https://outlook.office365.com").Token
+
+# Create providers
+$adProvider = New-IdleADIdentityProvider
+$exoProvider = New-IdleExchangeOnlineProvider
+
+# Create broker with mixed authentication types
+$broker = New-IdleAuthSession -SessionMap @{
+    # Active Directory uses Credential type
+    @{ AuthSessionName = 'AD' } = @{ AuthSessionType = 'Credential'; Credential = $adCredential }
+
+    # Exchange Online uses OAuth type
+    @{ AuthSessionName = 'EXO' } = @{ AuthSessionType = 'OAuth'; Credential = $exoToken }
+}
+
+# Use in plan
+$plan = New-IdlePlan -WorkflowPath './workflow.psd1' -Request $request -Providers @{
+    AD = $adProvider
+    EXO = $exoProvider
+    AuthSessionBroker = $broker
+}
+```
+
+In the workflow, steps specify which authentication session to use via `AuthSessionName`:
+
+```powershell
+# Step using AD (Credential)
+@{
+    Name = 'Create AD User'
+    Type = 'IdLE.Step.CreateIdentity'
+    With = @{
+        AuthSessionName = 'AD'
+        # ...
+    }
+}
+
+# Step using EXO (OAuth)
+@{
+    Name = 'Create Mailbox'
+    Type = 'IdLE.Step.CreateMailbox'
+    With = @{
+        AuthSessionName = 'EXO'
+        # ...
+    }
 }
 ```