Public/Initialize-PostureClient.ps1
|
# Copyright (c) 2026 Kainor LLC. Source-available, see LICENSE.md. function Initialize-PostureClient { <# .SYNOPSIS Sets up a client folder where you want it, with the licence in place, so Start-PostureRun has everything on the first run. .DESCRIPTION One-time, local, and the only thing it touches is the folder it creates: profile.json seeded with the tenant and client name, imports/ and hybrid/ for the files you provide, and tenantkeep.lic copied in when you pass -LicensePath. The licence is verified before anything is written: an ECDSA signature against the public keys built into the module, the tenant it names, its expiry. Nothing is sent anywhere and nothing in the tenant is read or changed. Without a licence the folder still works and the Conditional Access domain runs free. .PARAMETER Path The client folder. Default: ~/tenantkeep/clients/<client name, lower case, spaces to dashes>, so either -Path or a client name (-ClientName, or the customer named in the licence) is needed. .PARAMETER LicensePath The licence file to verify and copy into the folder as tenantkeep.lic. .PARAMETER TenantId The tenant this folder is for. The licence must name it; Start-PostureRun -Client refuses a sign-in to any other. Default: the tenant the licence names. .PARAMETER ClientName How the report names the customer. Default: the customer named in the licence. .PARAMETER PassThru Return the folder, licence status and tenant as an object instead of printing them. .EXAMPLE Initialize-PostureClient -LicensePath ~/Downloads/tenantkeep.lic .EXAMPLE Initialize-PostureClient -Path /Volumes/Clients/Contoso/posture -LicensePath ./tenantkeep.lic -TenantId contoso.onmicrosoft.com .EXAMPLE Initialize-PostureClient -Path ~/tenantkeep/clients/contoso -ClientName 'Contoso Ltd' # no licence yet: Conditional Access only #> [CmdletBinding(SupportsShouldProcess)] [OutputType([string], [pscustomobject])] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Setup summary for the admin at the console.')] param( [string] $Path, [string] $LicensePath, [ValidatePattern('^([0-9a-fA-F-]{36}|[A-Za-z0-9.-]+\.[A-Za-z]{2,})$')] [string] $TenantId, [string] $ClientName, [switch] $PassThru ) $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest # 1. The licence, verified before anything is written. $licence = $null if ($LicensePath) { $LicensePath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($LicensePath) if (-not (Test-Path -LiteralPath $LicensePath -PathType Leaf)) { throw "No licence file at $LicensePath." } $r = Test-PostureLicense -Path $LicensePath -TenantId $TenantId if (-not $r.valid) { throw "The licence at $LicensePath is not usable: $($r.reason)" } $licence = $r.licence if (-not $TenantId) { $TenantId = [string]$licence.tenantId } if (-not $ClientName) { $ClientName = [string]$licence.customer } } # 2. The folder. if (-not $Path) { if (-not $ClientName) { throw 'Pass -Path, or -ClientName, or a licence that names the customer, so the folder has a name.' } $slug = ($ClientName.ToLowerInvariant() -replace '[^a-z0-9]+', '-').Trim('-') if (-not $slug) { throw "'$ClientName' leaves nothing usable for a folder name; pass -Path." } $Path = Join-Path $HOME 'tenantkeep' 'clients' $slug } $Path = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path) if (-not $PSCmdlet.ShouldProcess($Path, 'Create the client folder')) { return } New-Item -ItemType Directory -Path $Path, (Join-Path $Path 'imports'), (Join-Path $Path 'hybrid') -Force | Out-Null # 3. The licence copy, the profile seed. Existing files are left alone. $licenceTarget = Join-Path $Path 'tenantkeep.lic' if ($licence) { if ((Resolve-Path -LiteralPath $LicensePath).Path -ne $licenceTarget) { Copy-Item -LiteralPath $LicensePath -Destination $licenceTarget -Force } } $profilePath = Join-Path $Path 'profile.json' if (-not (Test-Path -LiteralPath $profilePath)) { $seed = [ordered]@{} if ($TenantId) { $seed['tenantId'] = $TenantId } if ($ClientName) { $seed['clientName'] = $ClientName } if ($seed.Count -gt 0) { [System.IO.File]::WriteAllText($profilePath, ($seed | ConvertTo-Json) + "`n", [System.Text.UTF8Encoding]::new($false)) } } elseif ($TenantId) { $existing = Get-Content -Raw -LiteralPath $profilePath | ConvertFrom-Json -AsHashtable -Depth 10 $recorded = [string]$(if ($existing.Contains('tenantId')) { $existing['tenantId'] }) if ($recorded -and $recorded -ne $TenantId) { throw "$profilePath already belongs to tenant $recorded, not $TenantId. Use another folder." } } # 4. What the admin has now. $status = Get-PostureLicense -Path $(if (Test-Path -LiteralPath $licenceTarget) { $licenceTarget } else { [System.IO.Path]::Combine($Path, 'no-licence') }) -TenantId $TenantId $tierLine = $(if ($status.Valid) { "$($status.Tier) tier for $($status.Customer), expires $(([datetime]$status.ExpiresUtc).ToString('yyyy-MM-dd'))" } else { 'no licence: the Conditional Access domain runs free, everything else needs the Full tier (https://tenantkeep.app/licensing/)' }) $next = "Start-PostureRun -Client '$Path'$(if ($TenantId) { " -TenantId $TenantId" })" if ($PassThru) { return [pscustomobject]@{ Path = $Path; TenantId = $TenantId; ClientName = $ClientName; Licence = $status; Next = $next } } Write-Host "Client folder: $Path" Write-Host "Licence: $tierLine" if ($TenantId) { Write-Host "Tenant: $TenantId" } Write-Host "Next: $next" return $Path } |