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:
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 |
The configuration tab or dialog that triggered the validation request |
|
ConfigParameters |
KeyedCollection<string, ConfigParameter |
Table of configuration parameters for the Connector. |
Credential |
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 |
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:
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 |
---|---|
Indicates if the connector will support distinguished names and if so, what style. |
|
Determines the type of objects that are presented to the Export script.
|
|
Instructs the Synchronization Service to normalize anchor attributes before they are provided to scripts. |
|
Configures the pending import behavior in the Synchronization Service.
|
|
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 |
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 |
Contains any credentials entered by the administrator on the Connectivity tab. |
|
ParentNode |
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 |
Contains any credentials entered by the administrator on the Connectivity tab. |
|
OpenImportConnectionRunStep |
Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size. |
|
Types |
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 |
Contains any credentials entered by the administrator on the Connectivity tab. |
|
GetImportEntriesRunStep |
Holds the watermark (CustomData) that can be used during paged imports and delta imports |
|
OpenImportConnectionRunStep |
Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size. |
|
Types |
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 |
Contains any credentials entered by the administrator on the Connectivity tab. |
|
OpenImportConnectionRunStep |
Informs the script about the type of import run (delta or full), partition, hierarchy, watermark, and expected page size. |
|
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 |
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 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 |
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 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 |
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 |
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 |
Contains any credentials entered by the administrator on the Connectivity tab. |
|
Partition |
Directory partition that the CSEntry is in |
|
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 |
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:
PasswordPolicyViolationException– Thrown if the password does not meet the password policy in the connected system.
PasswordIllFormedException – Thrown if the password is not acceptable for the connected system.
PasswordExtension– Thrown for all other errors in the password script.
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:
Open the %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\bin\miiserver.exe.config file using a text editor.
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:
Create the directory c:\logs.
Grant the service account for the synchronization service Modify permissions to the c:\logs directory.
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