Public/Connect-PostureSession.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Connect-PostureSession { <# .SYNOPSIS One sign-in for every service the posture run reads. Opens the browser, holds the session in memory. .DESCRIPTION Signs the admin in to the TenantKeep Posture app (a multi-tenant public client with delegated, read-only permissions; see app.json and docs/plan-one-signin.md) with the authorization code flow and PKCE on a loopback port, in plain PowerShell. From that one sign-in the module gets a token for each service as it needs one (Get-PostureToken) and opens the Graph session right away. The refresh token lives in this process only and is never written to disk. Every token is the signed-in admin's, bounded by that admin's own roles. A tenant that has not consented to the app yet is told so, with the admin consent link. A Conditional Access policy that blocks the sign-in is reported with the app id, so the admin can allow it; the module does not work around it. Pass -TenantId to refuse a sign-in to any other tenant. .PARAMETER TenantId Tenant id or a verified domain. Default: organizations, which lets the admin pick the tenant in the browser. With a tenant id, the sign-in is refused if the account that signs in belongs to another tenant. .PARAMETER DeviceCode Use the device code flow: a code to type into a browser on another machine. For a box without a browser. .PARAMETER NoBrowser Print the sign-in URL instead of opening the browser. .PARAMETER ClientId A customer-owned app registration with the same delegated permissions, instead of the Kainor-owned one. .PARAMETER TimeoutSeconds How long to wait for the sign-in to come back. Default 300. .EXAMPLE Connect-PostureSession -TenantId contoso.onmicrosoft.com Invoke-PostureCollection -OutRoot ~/tenantkeep/evidence .EXAMPLE Connect-PostureSession -DeviceCode #> [CmdletBinding(DefaultParameterSetName = 'Browser')] [OutputType([hashtable])] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Sign-in instructions are for the console.')] param( [ValidatePattern('^([0-9a-fA-F-]{36}|[A-Za-z0-9.-]+\.[A-Za-z]{2,}|organizations)$')] [string] $TenantId = 'organizations', [Parameter(ParameterSetName = 'DeviceCode')] [switch] $DeviceCode, [Parameter(ParameterSetName = 'Browser')] [switch] $NoBrowser, [ValidatePattern('^[0-9a-fA-F-]{36}$')] [string] $ClientId, [ValidateRange(30, 1800)] [int] $TimeoutSeconds = 300 ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest $manifest = Get-PostureAppManifest $clientId = $(if ($ClientId) { $ClientId } else { [string]$manifest['clientId'] }) if (-not $clientId) { throw 'app.json carries no clientId: this build has no app registration to sign in to. Pass -ClientId for a registration of your own.' } $scope = 'openid profile offline_access https://graph.microsoft.com/.default' $consentLink = "https://login.microsoftonline.com/organizations/adminconsent?client_id=$clientId&redirect_uri=$([uri]::EscapeDataString([string]$manifest['consentRedirectUri']))" try { if ($DeviceCode) { $dc = Invoke-PostureTokenRequest -Endpoint devicecode -TenantId $TenantId -Form @{ client_id = $clientId; scope = $scope } Write-Host '' Write-Host ([string]$dc['message']) -ForegroundColor Cyan $interval = [int]$(if ($dc.ContainsKey('interval')) { $dc['interval'] } else { 5 }) $deadline = [datetime]::UtcNow.AddSeconds([int]$dc['expires_in']) $tokens = $null while (-not $tokens) { if ([datetime]::UtcNow -gt $deadline) { throw 'The device code expired before the sign-in completed. Run the command again.' } Start-Sleep -Seconds $interval $poll = Invoke-PostureTokenRequest -Endpoint token -TenantId $TenantId -Form @{ grant_type = 'urn:ietf:params:oauth:grant-type:device_code'; client_id = $clientId; device_code = [string]$dc['device_code'] } if ($poll.ContainsKey('access_token')) { $tokens = $poll } elseif ([string]$poll['error'] -eq 'slow_down') { $interval += 5 } } } else { $verifierBytes = [byte[]]::new(32) [System.Security.Cryptography.RandomNumberGenerator]::Fill($verifierBytes) $verifier = [Convert]::ToBase64String($verifierBytes).TrimEnd('=').Replace('+', '-').Replace('/', '_') $challenge = [Convert]::ToBase64String([System.Security.Cryptography.SHA256]::HashData([System.Text.Encoding]::ASCII.GetBytes($verifier))).TrimEnd('=').Replace('+', '-').Replace('/', '_') $state = [guid]::NewGuid().ToString('n') $loopback = New-PostureLoopbackListener $query = @( "client_id=$clientId", 'response_type=code', "redirect_uri=$([uri]::EscapeDataString($loopback['redirectUri']))", "scope=$([uri]::EscapeDataString($scope))", "state=$state", "code_challenge=$challenge", 'code_challenge_method=S256', 'prompt=select_account' ) -join '&' $url = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/authorize?$query" $opened = $false if (-not $NoBrowser) { try { Start-Process $url; $opened = $true } catch { Write-Verbose "Browser did not open: $($_.Exception.Message)" } } Write-Host '' if ($opened) { Write-Host 'Sign in to TenantKeep Posture in the browser window that just opened.' -ForegroundColor Cyan } else { Write-Host 'Open this address in a browser and sign in:' -ForegroundColor Cyan; Write-Host " $url" } $code = Wait-PostureAuthCode -Loopback $loopback -State $state -TimeoutSeconds $TimeoutSeconds $tokens = Invoke-PostureTokenRequest -Endpoint token -TenantId $TenantId -Form @{ grant_type = 'authorization_code'; client_id = $clientId; code = $code; redirect_uri = $loopback['redirectUri']; code_verifier = $verifier; scope = $scope } } } catch { $text = $_.Exception.Message if ($text -match 'AADSTS65001|consent_required|AADSTS650') { throw "This tenant has not consented to TenantKeep Posture yet. An admin consents once, here: $consentLink Then run the command again. ($text)" } if ($text -match 'AADSTS5300\d|AADSTS530032') { throw "A Conditional Access policy in this tenant blocked this sign-in to TenantKeep Posture (app id $clientId). The policy says what it wants: a compliant device, an approved app, or an exclusion for the admin running the report. Nothing was read. ($text)" } throw } $claims = ConvertFrom-PostureJwt -Token ([string]$tokens['access_token']) $tid = [string]$claims['tid'] $account = [string]$(foreach ($k in 'upn', 'preferred_username', 'unique_name') { if ($claims.ContainsKey($k) -and $claims[$k]) { $claims[$k]; break } }) if ($TenantId -match '^[0-9a-fA-F-]{36}$' -and $tid -ne $TenantId) { throw "Signed in to tenant $tid, but -TenantId $TenantId was asked for. Nothing was read; sign in with an account in that tenant." } $now = [datetime]::UtcNow $script:PostureSession = @{ clientId = $clientId tenantId = $tid tenantName = $null account = $account refreshToken = [string]$tokens['refresh_token'] signedInUtc = $now tokens = @{ graph = @{ accessToken = [string]$tokens['access_token']; expiresUtc = $now.AddSeconds([int]$tokens['expires_in']); scope = [string]$(if ($tokens.ContainsKey('scope')) { $tokens['scope'] }) } } } if (-not $script:PostureSession['refreshToken']) { throw 'The sign-in returned no refresh token (offline_access missing from consent?). Other services cannot be reached from it.' } Connect-PostureService -Name graph $null = Assert-PostureGraphScope -RequiredScope @('Directory.Read.All') $org = Invoke-PostureGraphRequest -ApiVersion v1.0 -Uri 'organization?$select=id,displayName,verifiedDomains' -Single $orgValue = $(if ($org -is [hashtable] -and $org.ContainsKey('value')) { @($org['value'])[0] } else { $org }) $initial = @($orgValue['verifiedDomains'] | Where-Object { $_['isInitial'] -eq $true }) if ($initial.Count -gt 0) { $script:PostureSession['tenantName'] = ([string]$initial[0]['name'] -replace '\.onmicrosoft\.com$', '') } $script:PostureSession['tenantDisplayName'] = [string]$orgValue['displayName'] Write-Host "Signed in as $account to $($script:PostureSession['tenantDisplayName']) ($tid)." -ForegroundColor Green return @{ tenantId = $tid tenantName = $script:PostureSession['tenantName'] tenantDisplayName = $script:PostureSession['tenantDisplayName'] account = $account clientId = $clientId scopes = @(([string]$(if ($claims.ContainsKey('scp')) { $claims['scp'] })) -split ' ' | Where-Object { $_ } | Sort-Object) expiresUtc = $script:PostureSession['tokens']['graph']['expiresUtc'] } } |