Private/Connect-PostureService.ps1

# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md.
function Connect-PostureService {
    <#
    .SYNOPSIS
        The one place in the module that opens a service session, always with an access token from the broker.
    .DESCRIPTION
        Delegated tokens only: no secret, no certificate, no password ever passes through here. Each service module
        is given its token and the companions it documents. The one exception is Purview: the Exchange Online
        Protection principal exposes no delegated scopes, so no third-party app can get a Security & Compliance
        PowerShell token, and the Exchange module signs the same admin in with its own app (a browser window, or a
        device code when the run has none). A session that is already open for the same tenant is left alone unless
        -Force. The read-only guard in the tests allows Connect-* calls in this file only.
    .PARAMETER Name
        graph, exchange, purview, sharepoint, teams or azure.
    #>

    [CmdletBinding()]
    [OutputType([void])]
    param(
        [Parameter(Mandatory)] [ValidateSet('graph', 'exchange', 'purview', 'sharepoint', 'teams', 'azure')] [string] $Name,
        [switch] $Force
    )

    $ErrorActionPreference = 'Stop'
    $session = $script:PostureSession
    if (-not $session) { throw 'No session. Run Connect-PostureSession first.' }
    $tenantId = [string]$session['tenantId']
    $account = [string]$session['account']
    switch ($Name) {
        'graph' {
            $token = Get-PostureToken -Resource graph -AsSecureString
            Connect-MgGraph -AccessToken $token -NoWelcome
        }
        'exchange' {
            # ExchangeOnlineManagement 3.1+. A delegated token for https://outlook.office365.com with Exchange.Manage pairs
            # with -UserPrincipalName (Michev, 2023; verify on the first live run).
            $token = Get-PostureToken -Resource exchange
            Connect-ExchangeOnline -AccessToken $token -UserPrincipalName $account -ShowBanner:$false
        }
        'purview' {
            # Seen live in Kainor, 2026-10-23: the Exchange Online Protection principal (00000007-0000-0ff1-ce00-000000000000)
            # exposes no delegated scopes at all, so the sign-in app cannot ask for one and the broker has no token to give.
            # Security & Compliance PowerShell signs the same admin in again through the Exchange module's own first-party
            # app. Still delegated, still bounded by that admin's roles, nothing stored. -Device when the run has no browser
            # (verify: Connect-IPPSSession -Device on the first live run).
            $ipps = @{ UserPrincipalName = $account; ShowBanner = $false }
            if ($session.ContainsKey('purviewSignIn') -and [string]$session['purviewSignIn'] -eq 'device') { $ipps['Device'] = $true }
            Connect-IPPSSession @ipps
        }
        'sharepoint' {
            # PnP cannot refresh a supplied token and the audience must match -Url (pnp/powershell #305), so the token is for
            # the admin site and fresh each time this runs.
            $token = Get-PostureToken -Resource sharepoint -Force
            Connect-PnPOnline -Url "https://$($session['tenantName'])-admin.sharepoint.com" -AccessToken $token
        }
        'teams' {
            $tokens = @((Get-PostureToken -Resource graph), (Get-PostureToken -Resource teams))
            Connect-MicrosoftTeams -AccessTokens $tokens | Out-Null
        }
        'azure' {
            $token = Get-PostureToken -Resource azure
            Connect-AzAccount -AccessToken $token -AccountId $account -Tenant $tenantId -SkipContextPopulation | Out-Null
        }
    }
    Write-Verbose "$Name session opened for $account in $tenantId."
}

function Disconnect-PostureService {
    <#
    .SYNOPSIS
        Closes the Graph session the broker opened. Other modules keep their own sessions until the process ends.
    #>

    [CmdletBinding()]
    [OutputType([void])]
    param()

    $ErrorActionPreference = 'Stop'
    if (Get-Command Disconnect-MgGraph -ErrorAction SilentlyContinue) { try { Disconnect-MgGraph | Out-Null } catch { Write-Verbose "Disconnect-MgGraph: $($_.Exception.Message)" } }
}