IAM Core
Connector PowerShell Module
On this page
The module Fortytwo.IAM.Core.Connector is for building an API based connector in PowerShell. It wraps the Connector API and, more usefully, works out for you which objects need to be created, updated and deleted on each import.
Installing the module
Install-Module Fortytwo.IAM.Core.Connector -Scope CurrentUserAuthenticate and Connect
A connector authenticates as an application, so create an access token profile for the app registration that the connector was created with, then connect using the connector's id:
Add-EntraIDClientSecretAccessTokenProfile `
-Name "MyConnector" `
-TenantId "00000000-0000-0000-0000-000000000000" `
-ClientId "<the app registration client id>" `
-ClientSecret ($Secret | ConvertTo-SecureString -AsPlainText -Force) `
-Scope "https://api.fortytwo.io/.default"
Connect-Connector -ConnectorId "<the connector id>" -AccessTokenProfile "MyConnector"See setting up for how the app registration and the connector are tied together.
Import data
First party connector
The Fortytwo first party connectors have the necessary code for doing an import. All you have to do is to trigger an import job.
$connector = Get-IAMCoreConnector | Where-Object {$_.name -eq 'Entra ID Inbound'}
New-IAMCoreSyncJob -Jobtype ConnectorImport -ConnectorId $connector.idAPI based connector
The heart of the module is the import session. Rather than issuing individual creates and deletes, you declare the complete set of objects the source system currently contains, and the module compares that against the connector space to work out what actually changed.
# Begin an import
Start-ConnectorSyncSession
# Add every object the source system currently has
foreach ($Employee in Get-MyEmployees) {
Build-ConnectorObject `
-ExternalId $Employee.Id `
-ObjectType "person" `
-Data @{
id = $Employee.Id
names = @{
firstname = $Employee.FirstName
lastname = $Employee.LastName
}
nin = $Employee.NationalId
} | Add-ConnectorSyncSessionObject
}
# Work out what changed, then apply it
$Operations = Get-ConnectorSyncSessionOperation
$Operations | Complete-ConnectorSyncSessionOperationBecause the session is a declaration of the full current state, objects that were in the connector space but were not added to the session are deleted. This is what makes deletions work — see how full imports work.
If the source system fails halfway through and you only add half the objects, the missing half will be deleted. Let the import fail loudly rather than completing a session with partial data. Get-ConnectorSyncSessionOperation refuses an empty session unless you pass -AllowEmptySession, which guards against the worst case.
To see what a session is about to do before applying it:
Get-ConnectorSyncSessionOperationStatisticsSynchronize changes
Populating the connector space does not change any core objects on its own. Run a synchronization to have the sync rules evaluated — this is done with the admin module, not this one:
New-IAMCoreSyncJob | Wait-IAMCoreSyncJobCmdlets
| Cmdlet | Purpose |
|---|---|
Connect-Connector | Connect as the connector's application. Takes -ConnectorId and -AccessTokenProfile. |
Get-ConnectorConfiguration | The connector's own configuration, including any inputs configured on it. |
Get-ConnectorData | Read the current contents of the connector space. |
Build-ConnectorObject | Build one object from -ExternalId, -ObjectType and -Data. |
Start-ConnectorSyncSession | Begin an import. |
Add-ConnectorSyncSessionObject | Add an object to the session. Accepts pipeline input. |
Get-ConnectorSyncSessionOperation | Compute the create, update and delete operations. |
Get-ConnectorSyncSessionOperationStatistics | Summarise those operations without applying them. |
Complete-ConnectorSyncSessionOperation | Apply the operations. |
Send-ConnectorFile | Upload a .zip for connectors that take a file rather than an API push. |
Write-ConnectorVerbose, Write-ConnectorError | Write to the connector's log, visible in the admin interface. |
Send-ConnectorLog | Send a log entry to IAM Core. |
ConvertFrom-ConnectorXmlToPowerShellObject | Helper for source systems that return XML. |