Public/ConnectedSystems/Get-JIMConnectedSystemServerCertificate.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Get-JIMConnectedSystemServerCertificate { <# .SYNOPSIS Reads the certificate a Connected System's server is presenting. .DESCRIPTION Connects to the endpoint the Connected System is configured for, purely to look at the certificate the server offers, and refuses it. Nothing is stored: trusting the certificate is a separate, explicit call to Approve-JIMConnectedSystemServerCertificate. The endpoint is always worked out by the Connected System's own connector from that system's settings; it is never named directly, so this cannot be used to make JIM connect to an address of your choosing. .PARAMETER ConnectedSystemId The ID of the Connected System whose server is asked. .PARAMETER SettingValues Connectivity settings entered but not yet saved, keyed by setting ID (from Get-JIMConnectorDefinition). Give them when configuring a Connected System that cannot be saved yet: JIM does not save settings that fail validation, and an untrusted certificate fails it, so without them JIM reads the endpoint last saved. They are never saved, and encrypted settings are ignored. .OUTPUTS The certificate the server presented, the chain JIM built from it, which check it fails and what to do, and when it was read. .EXAMPLE Get-JIMConnectedSystemServerCertificate -ConnectedSystemId 42 Reads the certificate the configured server is presenting. .EXAMPLE Get-JIMConnectedSystemServerCertificate -ConnectedSystemId 42 | Select-Object -ExpandProperty certificate | Select-Object host, subject, thumbprint, failureReason Shows the identifying details and which check the certificate fails. .EXAMPLE Get-JIMConnectedSystemServerCertificate -ConnectedSystemId 42 -SettingValues @{ 40 = 'https://hr.corp.local/scim/v2' } Reads the certificate presented by an endpoint that has been entered but not saved, using the Connector Definition Setting identifier for that connector's Base URL. .LINK Approve-JIMConnectedSystemServerCertificate Get-JIMConnectedSystem Get-JIMConnectorDefinition Get-JIMCertificate #> [CmdletBinding()] [OutputType('JIM.ServerCertificateResponse')] param( # Aliased so a Connected System object pipes in; the noun here is the certificate, not the system, # so -Id unambiguously means "the Connected System" (see src/JIM.PowerShell/CLAUDE.md). [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [Alias('Id')] [int]$ConnectedSystemId, [hashtable]$SettingValues ) process { # Check connection first if (-not $script:JIMConnection) { Write-Error "You are not connected to JIM. Run Connect-JIM -Url <your JIM URL> to authenticate, then try again." return } Write-Verbose "Reading the server certificate for Connected System: $ConnectedSystemId" try { $endpoint = "/api/v1/synchronisation/connected-systems/$ConnectedSystemId/server-certificate" if ($PSBoundParameters.ContainsKey('SettingValues')) { # Unsaved settings cannot travel on a GET, so the same read is available as a POST. $body = @{ settingValues = ConvertTo-JIMSettingValueUpdates -SettingValues $SettingValues } Invoke-JIMApi -Endpoint $endpoint -Method 'POST' -Body $body } else { Invoke-JIMApi -Endpoint $endpoint } } catch { Write-Error "Failed to read the server certificate: $_" } } } |