Windows PowerShell Connector technical reference

This article describes the Windows PowerShell Connector. The article applies to the following products:

  • Microsoft Identity Manager 2016 (MIM2016)
  • Forefront Identity Manager 2010 R2 (FIM2010R2)
    • Must use hotfix 4.1.3671.0 or later KB3092178.

For MIM2016 and FIM2010R2, the Connector is available as a download from the Microsoft Download Center.

Overview of the PowerShell Connector

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.5.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

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.

Create 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.

Connectivity

You can configure the following Connectivity parameters:

Connectivity

Parameter Default Value Purpose
Server Server name that the connector should connect to.
Domain Domain of the credential to store for use when the connector is run.
User Username of the credential to store for use when the connector is run.
Password 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:

Name Data Type Description
ConfigParameterPage ConfigParameterPage The configuration tab or dialog that triggered the validation request.
ConfigParameters KeyedCollection [string, ConfigParameter] Table of configuration parameters for the Connector.
Credential PSCredential 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:

Name Data Type Description
ConfigParameters KeyedCollection [string, ConfigParameter] Table of configuration parameters for the Connector.
Credential PSCredential 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.

Capabilities

Capability Description
Distinguished Name Style Indicates if the connector supports distinguished names and if so, what style.
Export Type 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
  • Data Normalization Instructs the Synchronization Service to normalize anchor attributes before they are provided to scripts.
    Object Confirmation 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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential 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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    ParentNode HierarchyNode 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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size.
    Types Schema Schema for the connector space that is imported.

    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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    GetImportEntriesRunStep ImportRunStep Holds the watermark (CustomData) that can be used during paged imports and delta imports.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size.
    Types Schema Schema for the connector space that is imported.

    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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    OpenImportConnectionRunStep OpenImportConnectionRunStep Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size.
    CloseImportConnectionRunStep CloseImportConnectionRunStep 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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informs the script about the type of export run (delta or full), partition, hierarchy, and expected page size.
    Types Schema Schema for the connector space that is exported.

    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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    CSEntries IListCSEntryChange List of all the connector space objects with pending exports to be processed during this pass.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informs the script about the type of export run (delta or full), partition, hierarchy, and expected page size.
    Types Schema Schema for the connector space that is exported.

    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:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    OpenExportConnectionRunStep OpenExportConnectionRunStep Informs the script about the type of export run (delta or full), partition, hierarchy, and expected page size.
    CloseExportConnectionRunStep CloseExportConnectionRunStep Informs the script about the reason the export was ended.

    The script should not return any output to the pipeline.

    Password Synchronization

    Windows PowerShell connectors can be used as a target for password changes/resets.

    The password script receives the following parameters from the connector:

    Name Data Type Description
    ConfigParameters KeyedCollection[string, ConfigParameter] Table of configuration parameters for the Connector.
    Credential PSCredential Contains any credentials entered by the administrator on the Connectivity tab.
    Partition Partition Directory partition that the CSEntry is in.
    CSEntry CSEntry Connector space entry for the object that is received a password change or reset.
    OperationType String Indicates if the operation is a reset (SetPassword) or a change (ChangePassword).
    PasswordOptions PasswordOptions 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:

    Sample Connectors

    For a complete overview of the available sample connectors, see Windows PowerShell Connector Sample Connector Collection.

    Other notes

    Additional Configuration for Impersonation

    Grant the user that is impersonated the following permissions on the Synchronization Service server:

    Read access to the following registry keys:

    • HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
    • HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Environment

    To determine the Security Identifier (SID) of the Synchronization Service service account, run the following PowerShell commands:

    $account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
    $account.Translate([System.Security.Principal.SecurityIdentifier]).Value
    

    Read access to the following file system folders:

    • %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions
    • %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache
    • %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}

    Substitute the name of the Windows PowerShell connector for the {ConnectorName} placeholder.

    Troubleshooting