Public/Connect-Connector.ps1
|
<# .SYNOPSIS Establishes a connection to the Fortytwo IAM Core Connector API. .DESCRIPTION Authenticates and configures the module session for use with the Fortytwo IAM Core Connector API. Sets the API root URL and access token profile used by all subsequent cmdlets in this module. Must be called before any other cmdlets in this module. Supports three parameter sets: - Default: Connects to the standard (external) API endpoint. - Internal: Connects to an internal API endpoint for a specific tenant. - Development: Connects to a custom API root URL for local development. .PARAMETER ConnectorId The GUID identifying the connector in the Fortytwo IAM platform. .PARAMETER AccessTokenProfile The name of the Entra ID access token profile to use for authentication. Defaults to "default". .PARAMETER Environment The target environment. Must be "production" (default) or "development". .PARAMETER APIVersion The API version to use. Currently only "beta" is supported. .PARAMETER TenantId (Internal parameter set) The GUID of the tenant to connect to via the internal API endpoint. .PARAMETER ApiRoot (Development parameter set) A custom API root URL for local development. Must end with 'iamcore/{APIVersion}/sync/connectors/{ConnectorId}/'. .EXAMPLE Connect-Connector -ConnectorId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" .EXAMPLE Connect-Connector -ConnectorId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -Environment development .EXAMPLE Connect-Connector -ConnectorId "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -ApiRoot "https://localhost/iamcore/beta/sync/connectors/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/" #> function Connect-Connector { [CmdletBinding(DefaultParameterSetName = 'Default')] param ( [Parameter(Mandatory = $true)] [ValidatePattern('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')] $ConnectorId, [Parameter(Mandatory = $false)] $AccessTokenProfile = "default", [Parameter(Mandatory = $false)] [ValidateSet("production", "development")] $Environment = "production", [Parameter(Mandatory = $false)] [ValidateSet("beta")] $APIVersion = "beta", [Parameter(Mandatory = $true, ParameterSetName = 'Internal')] [ValidatePattern('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$')] [string] $TenantId, [Parameter(Mandatory = $true, ParameterSetName = 'Development')] [ValidateScript({ $_ -match '^https?://.+$' })] [string] $ApiRoot ) $Script:APIRoot = $null $Script:AccessTokenProfile = $null $Script:ConnectorConfiguration = $null if (!(Get-EntraIDAccessTokenProfile -Profile $AccessTokenProfile)) { throw "Access token profile '$AccessTokenProfile' not found. Please create it using New-EntraIDAccessTokenProfile." } $Script:AccessTokenProfile = $AccessTokenProfile if ($PSCmdlet.ParameterSetName -eq "Development") { Write-Verbose "Using development Environment with API root: $ApiRoot" if ($ApiRoot -notlike "*iamcore/$($APIVersion)/sync/connectors/$ConnectorId/") { throw "When using the Development parameter set, the ApiRoot must end with 'iamcore/$($APIVersion)/sync/connectors/{ConnectorId}/'" } $Script:APIRoot = $ApiRoot } elseif ($PSCmdlet.ParameterSetName -eq "Internal") { $authsettings = Get-ConnectorAuthSettings -Internal -Development:($Environment -eq "development") Write-Verbose "Using internal $Environment environment" $Script:APIRoot = "https://$($authsettings.fqdn)/iamcore/$($APIVersion)/tenants/$($TenantId)/sync/connectors/$ConnectorId/" } else { $authsettings = Get-ConnectorAuthSettings -Development:($Environment -eq "development") Write-Verbose "Using $Environment environment" $Script:APIRoot = "https://$($authsettings.fqdn)/iamcore/$($APIVersion)/sync/connectors/$ConnectorId/" } # Try to get connector configuration $Script:ConnectorConfiguration = Get-ConnectorConfiguration } |