Windows PowerShell Connector for FIM 2010 R2 Technical Reference

Updated: January 10, 2015

The connector for Windows PowerShell enables administrators to rapidly integrate the FIM synchronization service with external systems that offer Windows PowerShell based application programming interfaces (APIs) as well as connect to systems without the need to develop compiled code. 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.

Connector Installation and Configuration

The connector is available as a downloadable MSI package from the Microsoft Download Center. Once downloaded, the connector can be installed on the synchronization service server. Following installation, the connector is immediately available for use inside of the synchronization service and can be configured via the synchronization service manager in the same manner as any other connector.

Prerequisites

Before you install the connector, make sure the following prerequisites are satisfied on the Synchronization Service server:

  • FIM 2010 R2 SP1 hotfix 4.1.3441 or better (KB 2832389)

  • Microsoft .NET 4.0 Framework

  • Windows PowerShell 2.0 or better

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 will run are digitally signed, configure the execution policy by running this command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Installation

To install the connector, execute the setup package that is available for download from the Microsoft Download Center. The setup package does not require any inputs specific to the connector.

Following installation, the connector will be installed in the Extensions folder under the Synchronization Service’s installation. By default this folder is located at:

%ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions

Creating a Windows PowerShell 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 will connect to and the functionality you require, the scripts you must implement will vary. This section outlines each of the scripts that can be implemented as well as when they are required.

The Windows PowerShell connector is designed to store each of the scripts inside of the Synchronization Service database. While it is possible to run scripts that are stored on the file system, it is much easier to insert the body of each script directly in to the connector’s configuration.

Once you have created a Windows PowerShell connector, you can run the connector via standard Run Profiles in the same manner as any other connector. For more information about Run Profiles, see Create a Management Agent Run Profile.

To Create a Windows PowerShell connector, use the Synchronization Service Management Agent Designer. Select the PowerShell (Microsoft) connector as shown below:

Create Management Agent

Connectivity and Configuration Scripts

Next you can supply configuration parameters for connecting to a remote system. These parameters will be 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:

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 will execute the Windows PowerShell scripts in the context of the credentials supplied above.

When possible, it is recommended that the $Credentials parameter passed to each script is used in lieu of impersonation.

For more information on additional permissions that are required to use this parameter, 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 user to be impersonated has a roaming profile, the connector will 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, refer to 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.

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 and connection credentials as well as 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 type(s) and attributes, and attribute constraints that the Synchronization Service will use when configuring attribute flow rules. The Schema Discovery script is executed during connector creation populate the connector’s schema and subsequently by the Refresh Schema function 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 comprised of SchemaType objects that represent object types (e.g. users, groups, etc.). The SchemaType object holds a collection of SchemaAttribute objects that represent the attributes (e.g. given name, surname, postal address, etc.) of the type.

To simplify the creation of the schema, the FIMPowerShellConnectorModule Windows PowerShell Module provides the following cmdlets:

  • New-FIMPSConnectorSchema

  • New-FIMPSConnectorSchemaType

  • Add-FIMPSConnectorSchemaAttribute

Common Module

The connector allows the administrator to store a shared Windows PowerShell module in the configuration. When the connector executes a script, the Windows PowerShell module is extracted to the file system so that it may 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")

Additional Parameters

In addition to the standard configuration settings discussed so far, 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 ( , ) as shown below:

Connectivity

To access custom configuration settings from a script, you must suffix the name with and 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

The FIMPowerShellConnectorModule Windows PowerShell Module includes a cmdlet, Get-FIMPSConnectorConfigurationSetting, to simplify access to configuration settings.

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 once the connector has been created. The table below lists each of the capability settings.

Capability Description

Distinguished Name Style

Indicates if the connector will support 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 of the 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 will import data via import scripts.

Enable Delta Import

When checked, the connector can request deltas from the import scripts.

Enable Export

When checked, the connector will export 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 and Run Scripts

The Global Parameters tab in the Management Agent Designer enables the administrator to configure each Windows PowerShell script that will be executed by the connector as well 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 must happen 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 which 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 administrators to browse for and select a set of containers that will be 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 source systems and conduct any preparatory steps prior to 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 will be imported

The script must return a single OpenImportConnectionResults object to the pipeline. The sample code below demonstrates how to return an OpenImportConnectionResults object to the pipeline:

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 and the synchronization service does not need to request any full object imports during a delta import. The Windows PowerShell connector has a page size of 9,999 objects. If your script will return 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 will be imported

The import data script must write a List<CSEntryChange> object to the pipeline. This collection is comprised 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 of the attributes for each individual 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).

To simplify the steps necessary to supply imported objects to the connector, the FIMPowerShellConnectorModule includes the following cmdlets:

  • New-FIMPSConnectorCSEntryChange

  • Add-FIMPSConnectorCSAttribute

End Import

At the conclusion of the import run, the End Import script will be run. This script should perform any cleanup tasks necessary (e.g. close connections to systems, respond to failures, etc.).

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. The sample code below demonstrates how to return a CloseImportConnectionResults object to the pipeline:

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 source systems and conduct any preparatory steps prior to exporting data from 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 will be exported

The script should not return any output to the pipeline.

Export Data

The Synchronization Service will call the Export Data script as many times as is necessary to process all of the pending exports. Depending on whether or not the connector space has more pending exports than the connector’s page size, the presence of reference attributes, or passwords, 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

IList<CSEntryChange>

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 will be exported

The export data script must return a PutExportEntriesResultsobject 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.

The sample code below demonstrates how 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 will be run. This script should perform any cleanup tasks necessary (e.g. close connections to systems, respond to failures, etc.).

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 for FIM 2010 R2 Sample Connector Collection

Troubleshooting

The Windows PowerShell connector supports logging and tracing of connector and script activities for troubleshooting purposes. Critical errors will be logged to the Application log on the Synchronization Service server and additional tracing can be enabled by the administrator.

Event Log

When a fatal error occurs while the PowerShell connector is running, or during the configuration of the connector in the Management Agent Designer, the Synchronization Service will log an event with the following details:

Setting Value

Log

Application

Level

Error

Source

FIMSynchronizationService

Event ID

6801

Task Category

Server

You can add additional event logging to Windows PowerShell scripts that are run by the connector by using the Write-EventLog cmdlet.

Logging/Tracing

The Windows PowerShell connector can be configured to emit tracing information to any .NET TraceListener (e.g. event log, XML file, text file, etc.). Administrators can also configure the connector to log information produced by the Write-Warning, Write-Verbose, and Write-Debug cmdlets to the trace log.

Enable Tracing

To enable tracing, follow these steps:

  1. Open the %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\bin\miiserver.exe.config file using a text editor.

  2. Paste the following XML in to the file on the line immediately following the <sources> tag

    <source name="ConnectorsLog" switchValue="Verbose">
        <listeners>
            <add initializeData="C:\Logs\ConnectorsTrace.log"
            type="System.Diagnostics.TextWriterTraceListener, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
            name="ConnectorsTraceListener">
                <filter type="" />
        </add>
        </listeners>
    </source> 
    

    The <System.Diagnostics> section of the miiserver.exe.config file should now resemble the following excerpt:

    Configuration

  3. Create the directory c:\logs.

  4. Grant the service account for the synchronization service Modify permissions to the c:\logs directory.

  5. Restart the synchronization service.

Trace Windows PowerShell Script Information

To trace information from Windows PowerShell scripts, add logging to your scripts in the form of Write-Verbose, Write-Debug, or Write-Progress statements.

Additional Configuration for Impersonation

Impersonated User Permissions

Grant the user that will be 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

    Note

    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>

    Note

    Substitute the name of the Windows PowerShell connector for the <ConnectorName> placeholder.

See Also

Other Resources

Extensible Connectivity 2.2 Management Agent Reference
Windows PowerShell Connector for FIM 2010 R2 Sample Connector Collection