Public/Connect/Connect-KB4Reporting.ps1
|
<# .SYNOPSIS Connects to the KnowBe4 Reporting API. .DESCRIPTION Stores an in-memory KnowBe4 Reporting API context for subsequent PSKB4Reporting commands. The API token is converted to a SecureString and is not written to disk. Use Disconnect-KB4Reporting to clear the context. .PARAMETER ApiToken The KnowBe4 Reporting API token. Accepts a plain string, SecureString, or PSCredential. Reporting API tokens are separate from KnowBe4 User Event API tokens. .PARAMETER Region The KnowBe4 region for the account. Valid values are US, EU, CA, UK, and DE. Defaults to US. .PARAMETER BaseUri Overrides the regional base URI. This is primarily useful for tests or future regional endpoints. The URI must use HTTPS. .PARAMETER PassThru Returns the sanitized connection context after connecting. .EXAMPLE Connect-KB4Reporting -ApiToken $env:KB4_REPORTING_API_TOKEN -Region US Connects to the US KnowBe4 Reporting API. .EXAMPLE Connect-KB4Reporting -ApiToken $secureToken -Region EU -PassThru Connects to the EU API and returns the public connection context. .OUTPUTS None by default. Returns a PSCustomObject when PassThru is specified. #> function Connect-KB4Reporting { [CmdletBinding()] param( [Parameter(Mandatory, ValueFromPipeline)] [ValidateNotNull()] [object] $ApiToken, [Parameter()] [ValidateSet('US', 'EU', 'CA', 'UK', 'DE')] [string] $Region = 'US', [Parameter()] [uri] $BaseUri, [Parameter()] [switch] $PassThru ) process { $secureToken = ConvertTo-KB4SecureString -InputObject $ApiToken $resolvedBaseUri = if ($PSBoundParameters.ContainsKey('BaseUri')) { $BaseUri } else { Get-KB4RegionBaseUri -Region $Region } if ($resolvedBaseUri.Scheme -ne 'https') { throw 'The KnowBe4 Reporting API requires an HTTPS base URI.' } $script:KB4ReportingContext = [pscustomobject] @{ Region = $Region BaseUri = $resolvedBaseUri ApiToken = $secureToken ConnectedAt = [DateTimeOffset]::UtcNow } if ($PassThru) { Get-KB4ReportingContext } } } |