--- title: PowerShell connector toolkit description: The PowerShell connector toolkit is not a complete connector in the traditional sense. Rather, it is a framework within which you must write your own PowerShell scripts to address your Microsoft Windows ecosystem requirements. You can use the PowerShell connector toolkit to create connectors that can provision any Microsoft system, including, but not limited to, Active Directory, Microsoft SQL, MS Exchange, SharePoint, Azure, and Office365. Any task you can perform with PowerShell can be executed through connectors based on this toolkit. component: openicf page_id: openicf:connector-reference:powershell canonical_url: https://docs.pingidentity.com/openicf/connector-reference/powershell.html section_ids: powershell-before-you-start: Before you start powershell-connector-setup: Install the PowerShell connector powershell-connector-configure: Configure the PowerShell connector powershell-connector-test: Test the PowerShell connector powershell-connector-test-correct: Check the connector configuration powershell-connector-search: Search user entries powershell-connector-create: Create users or groups powershell-connector-update: Update entries powershell-script-delete: Delete Users and Groups powershell-run-script-on-connector: Run Scripts Through the Connector config-connection-pooling-powershell: Configure connection pooling powershell-connector-azure: Manage Azure AD Objects With the PowerShell Connector azure-ad-systems: Set Up a Remote Connector Server powershell-azure-setup: Set Up the PowerShell Azure AD Scripts powershell-azure-test: Test the PowerShell Connector With Azure AD --- # PowerShell connector toolkit The PowerShell connector toolkit is not a complete connector in the traditional sense. Rather, it is a framework within which you must write your own PowerShell scripts to address your Microsoft Windows ecosystem requirements. You can use the PowerShell connector toolkit to create connectors that can provision any Microsoft system, including, but not limited to, Active Directory, Microsoft SQL, MS Exchange, SharePoint, Azure, and Office365. Any task you can perform with PowerShell can be executed through connectors based on this toolkit. The PowerShell connector toolkit is available from the [Backstage download site](https://backstage.forgerock.com/downloads/browse/idm/all/productId:idm-connector-servers/minorVersion:1.5/version:1.5.7.0/language:dot-net) and is bundled with the .NET remote connector server. To use this connector, you must write a PowerShell script for each operation that you want the connector to perform (create, read, update, delete, authenticate, and so on). Sample scripts for core operations are included with the .NET RCS. ## Before you start To implement a scripted PowerShell connector, you must install the following: * Microsoft .NET Framework 4.6.2 or later. Connectors created with the PowerShell connector toolkit run on the .NET platform and require the installation of a .NET connector server on the Windows system. To install the .NET connector server, follow the instructions in [Install .NET RCS](dotnet-server-reference.html). * PowerShell version 4.0 or above. * The PowerShell connector toolkit. ## Install the PowerShell connector To run the commands in this procedure, start with the PowerShell command line. Some commands require administrative privileges. 1. [Install, configure, and start the .NET connector server on a Windows host](dotnet-server-reference.html). If you are running an Active Directory Domain Controller, install the .NET connector server on the same host where the Windows PowerShell module is installed. 2. [Configure IDM to connect to the .NET connector server](configure-server.html). 3. The PowerShell connector toolkit comes bundled with the .NET RCS. To confirm installation, check the .NET RCS installation directory for the `MsPowerShell.Connector.dll` file. 4. Sample scripts are provided with the .NET remote connector server. Reference the full path to the scripts in your connector configuration, for example: ``` "CreateScriptFileName" : "C:/Program Files (x86)/ForgeRock/OpenICF/samples/ADCreate.ps1", ... ``` ## Configure the PowerShell connector 1. You cannot configure a PowerShell connector through the UI. Configure the connector over REST, as described in [Configure Connectors Over REST](configure-connector.html#connector-wiz-REST). 2. Alternatively, copy the sample connector configuration file (`provisioner.openicf-adpowershell.json` ) from the `samples\example-configurations\provisioners` directory to your project's `conf` directory. | | | | - | -------------------------------------------------------------------------------------------------------------------------------- | | | Paths in these files must use forward slash characters and not the backslash characters that you would expect in a Windows path. | 3. Verify that at least the path to the scripts and the connection and authentication details are correct for your deployment. **PowerShell Connector Configuration Properties** | Property | Type | Example | Encrypted\[[1](#_footnotedef_1 "View footnote.")] | Required\[[2](#_footnotedef_2 "View footnote.")] | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ | | `operationScriptFileName` | `String` | `C:/openidm/AD/ADCreate.ps1`, | [icon: times, set=fa]No | [icon: check, set=fa]Yes | | The full path to the script that implements the corresponding OpenICF operation. | | | | | | `VariablesPrefix` | `String` | `Connector` | [icon: times, set=fa]No | [icon: times, set=fa]No | | To avoid variable namespace conflicts, you can define a prefix for the connector variables. All variables are injected into the script under that prefix and can be used with the dotted notation. | | | | | | `QueryFilterType` | `String` | `AdPsModule` (for Active Directory) | [icon: times, set=fa]No | [icon: check, set=fa]Yes | | A configurable query filter visitor property that defines the format in which the query will be injected into the connector. Possible values are:- `Map` - the query filter is a map - `Ldap` - the query filter is in LDAP search format; for example, `"(cn=Joe)"` - `Native` - the query filter is a native OpenICF query filter - `AdPsModule` - the query filter is compatible with the Active Directory PowerShell module, `Get-ADUser Filter` | | | | | | `ReloadScriptOnExecution` | `Boolean` | `true` | [icon: times, set=fa]No | [icon: times, set=fa]No | | When `true`, the connector reloads the script from disk every time it is executed. This can be useful for debugging purposes. Set to `false` in production. | | | | | | `UseInterpretersPool` | `Boolean` | `true` | [icon: times, set=fa]No | [icon: times, set=fa]No | | If `true`, the connector leverages the PowerShell RunSpace Pool. | | | | | | `MaxInterpretersPoolSize` | `Integer` | `5` | [icon: times, set=fa]No | [icon: times, set=fa]No | | The maximum size of the interpreter pool. | | | | | | `MinInterpretersPoolSize` | `Integer` | `1` | [icon: times, set=fa]No | [icon: times, set=fa]No | | The minimum size of the interpreter pool. | | | | | | `PoolCleanupInterval` | `Double` | `60` | [icon: times, set=fa]No | [icon: times, set=fa]No | | Specifies the interval (in minutes) at which unused interpreter instances are discarded. To avoid cleaning up unused interpreter instances, set this property to `0`. | | | | | | `SubstituteUidAndNameInQueryFilter` | `Boolean` | `true` | [icon: times, set=fa]No | [icon: times, set=fa]No | | Specifies whether the `__UID__` and `__NAME__` should be replaced by the value defined in the `NameAttributeName` and `UidAttributeName` in the query filter. | | | | | | `UidAttributeName` | `String` | `ObjectGUID` | [icon: times, set=fa]No | [icon: times, set=fa]No | | The attribute on the resource that contains the object `__UID__`. | | | | | | `NameAttributeName` | `String` | `DistinguishedName` | [icon: times, set=fa]No | [icon: times, set=fa]No | | The attribute on the resource that contains the object `__NAME__`. | | | | | | `PsModulesToImport` | `Array` | `["ActiveDirectory","C:/openidm/samples/scripted-powershell-with-ad/tools/ADSISearch.psm1"]` | [icon: times, set=fa]No | [icon: times, set=fa]No | | An array of additional PowerShell modules that the connector must import. | | | | | | `Host` | `String` | `ad.example.com` | [icon: times, set=fa]No | [icon: check, set=fa]Yes | | The host name or IP address of the Active Directory server. | | | | | | `Port` | `Integer` | `null` | [icon: times, set=fa]No | [icon: check, set=fa]Yes | | The port number on which the remote resource listens for connections. | | | | | | `Login` | `String` | `""` | [icon: times, set=fa]No | [icon: times, set=fa]No | | The user account in the remote resource that is used for the connection. | | | | | | `Password` | `String` | `null` | [icon: lock, set=fa]Encrypted | [icon: check, set=fa]Yes | | The password of the user account that is used for the connection. | | | | | | `CustomProperties` | `Array` | `[ ]` | [icon: times, set=fa]No | [icon: times, set=fa]No | | An array of Strings to define custom configuration properties. Each property takes the format `"name=value"`. For example:```json "configurationProperties" : { ... "CustomProperties" : ["baseContext = CN=Users,DC=example,DC=com" ], ... } ```The custom property can then be read from the PowerShell scripts as follows:```PowerShell $base = $Connector.Configuration.PropertyBag.baseContext ``` | | | | | ## Test the PowerShell connector These examples show you how to test the connector is configured correctly and operating as expected. ### Check the connector configuration ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system/adpowershell?_action=test" { "name" : "adpowershell", "enabled" : true, "config" : "config/provisioner.openicf/adpowershell", "objectTypes" : [ "__ALL__", "group", "account" ], "connectorRef" : { "connectorName" : "Org.Forgerock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector", "bundleName" : "MsPowerShell.Connector", "bundleVersion" : "[1.4.3.0,1.5.0.0)" }, "displayName" : "PowerShell Connector", "ok" : true } ``` When you run this test, a log entry associated with the .NET connector server should be created in the `logs/` directory of that server. ### Search user entries You can use the connector, with a PowerShell search script, to retrieve information from a target system. The PowerShell search script accepts IDM queries, including `query-all-ids` and `_queryFilter`. The following command retrieves a list of users in an Active Directory server. You can also use any system-enabled filter, such as those described in [Presence Expressions](https://docs.pingidentity.com/pingidm/8/objects-guide/queries.html#query-presence): ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/system/adpowershell/account?_queryId=query-all-ids" ``` ### Create users or groups This command creates a new user in Active Directory: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --header "content-type: application/json" \ --data '{ "distinguishedName" : "CN=Robert Smith,CN=Users,DC=EXAMPLE,DC=COM", "sAMAccountName" : "robert.smith", "sn" : "Smith", "cn" : "Robert Smith", "userPrincipalName": "Robert.Smith@example.com", "enabled" : true, "password" : "Passw0rd", "telephoneNumber" : "0052-611-091" }' \ "http://localhost:8080/openidm/system/adpowershell/account?_action=create" ``` ### Update entries You can update the following properties with the sample scripts: * Password * Principal Name * License * Common user attributes This command changes the password for the user with the specified `_id`: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --header "content-type: application/json" \ --data '{ "operation": "replace", "Field": "password", "value": "Passw1rd" }' \ "http://localhost:8080/openidm/system/adpowershell/account/1d4c9276-6937-4d9e-9c60-67e8b4207f4e" ``` ### Delete Users and Groups This command deletes an Active Directory user entry with the specified `_id`: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://localhost:8080/openidm/system/adpowershell/account/1d4c9276-6937-4d9e-9c60-67e8b4207f4e" ``` ### Run Scripts Through the Connector The `runScriptOnConnector` operation lets you run an arbitrary script action through the connector. This operation takes the following variables as input: * `configuration` A handler to the connector's configuration object. * `options` A handler to the Operation Options. * `operation` The operation type that corresponds to the action (`RUNSCRIPTONCONNECTOR` in this case). * `log` A handler to the log. The script can return any object that can be serialized by OpenICF, such as `Boolean`, `String`, `Array`, or `Dictionary`. If the object type cannot be serialized, such as `Hashtable`, the script fails with the error: ``` "error": "No serializer for class: System.Collections.Hashtable" ``` To run an arbitrary script on the PowerShell connector, define the script in the `systemActions` property of your provisioner file: ```json "systemActions" : [ { "scriptId" : "MyScript", "actions" : [ { "systemType" : ".*PowerShellConnector", "actionType" : "PowerShell", "actionFile" : "scripts/Myactionscript.ps1" } ] } ] ``` When you have defined the script, you can call it over REST on the system endpoint, as follows: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system/adpowershell?_action=script&scriptId=MyScript¶m1=value1¶m2=value2" ``` You can also call it through the IDM script engine, as follows: ```none openidm.action("/system/adpowershell", "script", {}, {"scriptId": "MyScript", "param1": "value1", "param2": "value2"}) ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Because the action script is stored locally with IDM, it must be transmitted across the network every time it is called. An alternative approach is to write a PowerShell module and to load it using the `PsModulesToImport` option of the PowerShell connector. In this case, the action script is limited to a function call, and you do not need a script file on the IDM side.The following example uses the `actionSource` property in the provisioner, instead of the `actionFile` property, to call the action. The example calls a custom `Set-Exchange` function from a module loaded on the .Net connector server by the PowerShell connector:```json "systemActions" : [ { "scriptId" : "SetExchange", "actions" : [ { "systemType" : ".*PowerShellConnector", "actionType" : "PowerShell", "actionSource" : "Set-Exchange $Connector.Arguments.dn" } ] } ] ``` | ### Configure connection pooling The PowerShell connector uses [ICF pooling](pooling.html#icf-pooling) to manage connections. Learn more about the different pooling mechanisms in [Connectors by pooling mechanism](pooling.html#pooling-table). ## Manage Azure AD Objects With the PowerShell Connector The .NET Remote Connector Server (RCS) includes two sets of sample scripts in the `/path/to/openicf--dotnet/samples/AzureAD` directory. Use these scripts to manage objects in Azure AD using the PowerShell connector: * **Version 1**: These scripts are based on the older Microsoft Online (MSOL) V1 PowerShell module. For information on connecting to your Azure AD with this module, refer to the corresponding [Microsoft documentation](https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell#connect-with-the-microsoft-azure-active-directory-module-for-windows-powershell). Microsoft has expressed its intention to deprecate this module when its functionality has been completely migrated to the newer Azure Active Directory PowerShell for Graph Module. These scripts are supported only up to Windows 2012 R2. The Version 1 scripts can manage security groups but not dynamic groups. * **Version 2**: These scripts are based on the [Azure Active Directory PowerShell for Graph Module](https://docs.microsoft.com/en-us/powershell/module/Azuread/?view=azureadps-2.0). For information on connecting to your Azure AD with this module, refer to the corresponding [Microsoft documentation](https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell#connect-with-the-azure-active-directory-powershell-for-graph-module). The cmdlets in this module let you perform CRUD operations on an Azure AD instance, and configure the directory and its features. The Version 2 scripts can manage user password policies, security and mail groups, dynamic groups, and devices. Follow these procedures to use the sample Azure AD scripts with the PowerShell connector: ### Set Up a Remote Connector Server 1. Install a [.NET connector server](dotnet-server-reference.html) on your Windows host. These steps assume a Windows hostname of `windows-host.example.com`. 2. On `windows-host.example.com`, install the [PowerShell connector](#powershell-connector-setup). When you have installed the PowerShell connector, make sure that the ICF .NET connector server is still running. If it is not running, restart the connector server and check the logs. In some cases, Windows blocks the PowerShell connector .dll files. If the connector server fails to start, right-click on `MsPowerShell.Connector.dll` and select Properties > Security 3. If the following text displays: ``` This file came from another computer and might be blocked to help protect this computer. ``` Click Unblock to unblock the connector .dll file. Then, restart the connector server. 4. On `windows-host.example.com`, install the Windows Azure AD Module that corresponds to the version of the scripts you are using. * For Version 1 scripts, install the MSOnline module. * For Version 2 scripts, [install the Azure AD module](https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell#connect-with-the-azure-active-directory-powershell-for-graph-module). 5. These instructions assume that you have an existing Azure AD instance. Create a specific administrative account in Azure AD, to run the PowerShell connector scripts. 6. In a PowerShell window on `windows-host.example.com`, verify that your Windows host can connect to your Azure AD tenant: * For Version 1 scripts, run `Connect-MsolService`. * For Version 2 scripts, run `Connect-AzureAD`. ### Set Up the PowerShell Azure AD Scripts When all your systems are installed and running, and you have verified that your Windows host can connect to your Azure AD, set up the sample scripts as follows: 1. On `windows-host.example.com`, create a directory for the PowerShell scripts, for example: ``` PS C:\> mkdir -Path openidm\scripted-powershell-with-azure-ad\scripts ``` Use this scripts directory location when configuring the provisioner file. 2. Copy the V1 or V2 Azure AD scripts from the `/path/to/openicf--dotnet/samples/AzureAD` directory to the `scripts` directory you created in the previous step. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | By default, Windows doesn't trust downloaded scripts. To run the scripts, you might need to:- Run the [Unblock-File](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/unblock-file) cmdlet. This cmdlet unblocks downloaded PowerShell script files so you can run them regardless of the PowerShell execution policy. - [Change the PowerShell execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) so you can run the downloaded scripts. | 3. In IDM, [configure the connection to the .NET connector server](configure-server.html). 4. In IDM, [configure the PowerShell connector](#powershell-connector-configure). You can copy and use the sample provisioner file from the `/path/to/openicf--dotnet/samples/AzureAD` directory as a starting point. Set at least the following properties: | | | | ------------------ | ------------------------------------------------------------------------------------ | | `connectorHostRef` | The name of the connector server referenced in the previous step. | | `*ScriptFileName` | Set the path to the script directory that you created on `windows-host.example.com`. | ### Test the PowerShell Connector With Azure AD 1. Test that the connector has been configured correctly and can reach the Azure AD: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "http://localhost:8080/openidm/system/adpowershell?_action=test" { "name": "adpowershell", "enabled": true, "config": "config/provisioner.openicf/adpowershell", "objectTypes": [ "__ALL__", "account", "group" ], "connectorRef": { "bundleName": "MsPowerShell.Connector", "connectorName": "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector", "bundleVersion": "[1.4.3.0,1.5.0.0)" }, "displayName": "PowerShell Connector ", "ok": true } ``` If there is no response from this connector test, check your connector configuration and the connection to the .NET connector server. *** [1](#_footnoteref_1). Indicates whether the property value is considered confidential, and therefore encrypted in IDM.[2](#_footnoteref_2). A list of operations in this column indicates that the property is required for those operations.