The PowerShell Connector enables you to integrate the synchronization service with external systems that offer Windows PowerShell based APIs. The connector provides a bridge between the capabilities of the call-based extensible connectivity management agent 2 (ECMA2) framework and Windows PowerShell. For more information about the ECMA framework, see the Extensible Connectivity 2.2 Management Agent Reference.
Prerequisites
Before you use the Connector, make sure you have the following on the synchronization server:
Microsoft .NET 4.6.2 Framework or later
Windows PowerShell 2.0, 3.0, or 4.0
The execution policy on the Synchronization Service server must be configured to allow the connector to run Windows PowerShell scripts. Unless the scripts the connector runs are digitally signed, configure the execution policy by running this command: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Deploying this connector will require one or more PowerShell scripts. Some Microsoft products may provide scripts for use with this connector, and the support statement for those scripts would be provided by that product. If you are developing your own scripts for use with this connector, you will need to have familiarity with the Extensible Connectivity Management Agent API to develop and maintain those scripts. If you are integrating with third party systems using your own scripts in a production environment, we recommend you work with the third party vendor or a deployment partner for help, guidance and support for this integration.
Create a new Connector
To create a Windows PowerShell connector in the synchronization service, you must provide a series of Windows PowerShell scripts that execute the steps requested by the synchronization service. Depending on the data source you connect to and the functionality you require, the scripts you must implement varies. This section outlines each of the scripts that can be implemented and when they are required.
The Windows PowerShell connector is designed to store each of the scripts inside the Synchronization Service database. While it is possible to run scripts that are stored on the file system, it is easier to insert the body of each script directly in to the connector’s configuration.
To Create a PowerShell connector, in Synchronization Service select Management Agent and Create. Select the PowerShell (Microsoft) Connector.
Connectivity
Supply configuration parameters for connecting to a remote system. These values are securely stored by the Synchronization Service and made available to your Windows PowerShell scripts when the connector is run.
You can configure the following Connectivity parameters:
Connectivity
Parameter
Default Value
Purpose
Server
<Blank>
Server name that the connector should connect to.
Domain
<Blank>
Domain of the credential to store for use when the connector is run.
User
<Blank>
Username of the credential to store for use when the connector is run.
Password
<Blank>
Password of the credential to store for use when the connector is run.
Impersonate Connector Account
False
When true, the synchronization service runs the Windows PowerShell scripts in the context of the credentials supplied. When possible, it is recommended that the $Credentials parameter is passed to each script is used instead of impersonation. For more information on additional permissions that are required to use this option, see Additional Configuration for Impersonation.
Load User Profile When Impersonating
False
Instructs Windows to load the user profile of the connector’s credentials during impersonation. If the impersonated user has a roaming profile, the connector does not load the roaming profile. For more information on additional permissions that are required to use this parameter, see Additional Configuration for Impersonation.
Logon Type When Impersonating
None
Logon type during impersonation. For more information, see the dwLogonType documentation.
Signed Scripts Only
False
If true, the Windows PowerShell connector validates that each script has a valid digital signature. If false, ensure that the Synchronization Service server’s Windows PowerShell execution policy is RemoteSigned or Unrestricted.
Common Module
The connector allows you to store a shared Windows PowerShell module in the configuration. When the connector runs a script, the Windows PowerShell module is extracted to the file system so that it can be imported by each script.
For Import, Export, and Password Synchronization scripts, the common module is extracted to the connector’s MAData folder. For Schema, Validation, Hierarchy, and Partition discovery scripts, the common module is extracted to the %TEMP% folder. In both cases, the extracted Common Module script is named according to the Common Module Script Name setting.
To load a module called FIMPowerShellConnectorModule.psm1 from the MAData folder, use the following statement:
Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")
To load a module called FIMPowerShellConnectorModule.psm1 from the %TEMP% folder, use the following statement:
Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")
Parameter Validation
The Validation Script is an optional Windows PowerShell script that can be used to ensure that connector configuration parameters supplied by the administrator are valid. Validating server, connection credentials, and connectivity parameters are common usages of the validation script. The validation script is called after the following tabs and dialogs are modified:
Connectivity
Global Parameters
Partition Configuration
The validation script receives the following parameters from the connector:
Contains any credentials entered by the administrator on the Connectivity tab.
The validation script should return a single ParameterValidationResult object to the pipeline.
Schema Discovery
The Schema Discovery script is mandatory. This script returns the object types, attributes, and attribute constraints that the Synchronization Service uses when configuring attribute flow rules. The Schema Discovery script is run during connector creation and populates the connector’s schema. It is also used by the Refresh Schema action in the Synchronization Service Manager.
The schema discovery script receives the following parameters from the connector:
Contains any credentials entered by the administrator on the Connectivity tab.
The script must return a single Schema object to the pipeline. The Schema object is composed of SchemaType objects that represent object types (for example: users and groups). The SchemaType object holds a collection of SchemaAttribute objects that represent the attributes (for example: given name, surname, and postal address) of the type.
Additional Parameters
In addition to the standard configuration settings, you can define additional custom configuration settings that are specific to the instance of the Connector. These parameters can be specified at the connector, partition, or run step levels and accessed from the relevant Windows PowerShell script. Custom configuration settings can be stored in the Synchronization Service database in plain text format or they may be encrypted. The Synchronization Service automatically encrypts and decrypts secure configuration settings when required.
To specify custom configuration settings, separate the name of each parameter with a comma ( , ).
To access custom configuration settings from a script, you must suffix the name with an underscore ( _ ) and the scope of the parameter (Global, Partition, or RunStep). For example, to access the Global FileName parameter, use this code snippet: $ConfigurationParameters["FileName_Global"].Value
Capabilities
The capabilities tab of the Management Agent Designer defines the behavior and functionality of the connector. The selections made on this tab cannot be modified when the connector has been created. This table lists the capability settings.
Determines the type of objects that are presented to the Export script.
AttributeReplace – includes the full set of values for a multi-valued attribute when the attribute changes.
AttributeUpdate – includes only the deltas to a multi-valued attribute when the attribute changes.
MultivaluedReferenceAttributeUpdate - includes a full set of values for non-reference multi-valued attributes and only deltas for multi-valued reference attributes.
ObjectReplace – includes all attributes for an object when any attribute changes
Configures the pending import behavior in the Synchronization Service.
Normal – default behavior that expects all exported changes to be confirmed via import
NoDeleteConfirmation – when an object is deleted, there is no pending import generated.
NoAddAndDeleteConfirmation – when an object is created or deleted, there is no pending import generated.
Use DN as Anchor
If the Distinguished Name Style is set to LDAP, the anchor attribute for the connector space is also the distinguished name.
Concurrent Operations of Several Connectors
When checked, multiple Windows PowerShell connectors can run simultaneously.
Partitions
When checked, the connector supports multiple partitions and partition discovery.
Hierarchy
When checked, the connector supports an LDAP style hierarchical structure.
Enable Import
When checked, the connector imports data via import scripts.
Enable Delta Import
When checked, the connector can request deltas from the import scripts.
Enable Export
When checked, the connector exports data via export scripts.
Enable Full Export
When checked, the export scripts support exporting the entire connector space. To use this option, Enable Export must also be checked.
No Reference Values In First Export Pass
When checked, reference attributes are exported in a second export pass.
Enable Object Rename
When checked, distinguished names can be modified.
Delete-Add As Replace
When checked, delete-add operations are exported as a single replacement.
Enable Password Operations
When checked, password synchronization scripts are supported.
Enable Export Password in First Pass
When checked, passwords set during provisioning are exported when the object is created.
Global Parameters
The Global Parameters tab in the Management Agent Designer enables you to configure the Windows PowerShell scripts that are run by the connector. You can also configure global values for custom configuration settings defined on the Connectivity tab.
Partition Discovery
A partition is a separate namespace within one shared schema. For example, in Active Directory every domain is a partition within one forest. A partition is the logical grouping for import and export operations. Import and Export have partition as a context and all operations happens in this context. Partitions are supposed to represent a hierarchy in LDAP. The distinguished name of a partition is used in import to verify that all returned objects are within the scope of a partition. The partition distinguished name is also used during provisioning from the metaverse to the connector space to determine the partition an object should be associated with during export.
The partition discovery script receives the following parameters from the connector:
Contains any credentials entered by the administrator on the Connectivity tab.
The script must return a either a single Partition object or a List[T] of Partition objects to the pipeline.
Hierarchy Discovery
The hierarchy discovery script is only used when the Distinguished Name Style capability is LDAP. The script is used to allow you to browse and select a set of containers that is considered in or out of scope for import and export operations. The script should only provide a list of nodes that are direct children of the root node supplied to the script.
The hierarchy discovery script receives the following parameters from the connector:
The root node of the hierarchy under which the script should return direct children.
The script must return a either a single child HierarchyNode object or a List[T] of child HierarchyNode objects to the pipeline.
Import
Connectors that support import operations must implement three scripts.
Begin Import
The begin import script is run at the beginning of an import run step. During this step, you can establish a connection to the source system and do preparatory steps before importing data from the connected system.
The begin import script receives the following parameters from the connector:
The script must return a single OpenImportConnectionResults object to the pipeline, for example: Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)
Import Data
The import data script is called by the connector until the script indicates that there is no more data to import. The Windows PowerShell connector has a page size of 9,999 objects. If your script returns more than 9,999 objects for import, you must support paging. The connector exposes a custom data property that you can use to a store a watermark so that each time the import data script is called, your script resumes importing objects where it left off.
The import data script receives the following parameters from the connector:
The import data script must write a List[CSEntryChange] object to the pipeline. This collection is composed of CSEntryChange attributes that represent each object being imported. During a Full Import run, this collection should have a full set of CSEntryChange objects that have all attributes for every object. During a Delta Import, the CSEntryChange object should either contain the attribute level deltas for each object to import, or a complete representation of the objects that have changed (Replace mode).
End Import
At the conclusion of the import run, the End Import script is run. This script should perform any cleanup tasks necessary (for example, close connections to systems and respond to failures).
The end import script receives the following parameters from the connector:
Informs the script about the reason the import was ended.
The script must return a single CloseImportConnectionResults object to the pipeline, for example: Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)
Export
Identical to the import architecture of the connector, connectors that support Export must implement three scripts.
Begin Export
The begin export script is run at the beginning of an export run step. During this step, you can establish a connection to the source system and conduct any preparatory steps before exporting data to the connected system.
The begin export script receives the following parameters from the connector:
The script should not return any output to the pipeline.
Export Data
The Synchronization Service calls the Export Data script as many times as is necessary to process all pending exports. If the connector space has more pending exports than the connector’s page size, the export data script may be called multiple times and possibly multiple times for the same object.
The export data script receives the following parameters from the connector:
The export data script must return a PutExportEntriesResults object to the pipeline. This object does not need to include result information for each exported connector unless an error or a change to the anchor attribute occurs. For example, to return a PutExportEntriesResults object to the pipeline: Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)
End Export
At the conclusion of the export run, the End Export script to run. This script should perform any cleanup tasks necessary (for example, close connections to systems and respond to failures).
The end export script receives the following parameters from the connector:
Flags that specify the intended password reset behavior. This parameter is only available if OperationType is SetPassword.
OldPassword
String
Populated with the object’s old password for password changes. This parameter is only available if OperationType is ChangePassword.
NewPassword
String
Populated with the object’s new password that the script should set.
The password script is not expected to return any results to the Windows PowerShell pipeline. If an error occurs in the password script, the script should throw one of the following exceptions to inform the Synchronization Service about the problem:
This module examines the Microsoft Entra Connect Sync and Microsoft Entra Cloud Sync installation requirements, the options for installing and configuring the tools, and how to monitor synchronization services using Microsoft Entra Connect Health.
Demonstrate the use of Microsoft Power Platform solutions to simplify, automate, and empower business processes for organizations in the role of a Functional Consultant.