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. It is also 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.
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.

Install, configure, and start the .NET connector server on a Windows host. If you are running an Active Directory Domain Controller, install the .NET connector server on the same host on which the Windows PowerShell module is installed.
Configure IDM to connect to the .NET connector server.
The PowerShell connector toolkit comes bundled with the .NET RCS. To confirm it is installed, check the .NET RCS installation directory for a MsPowerShell.Connector.dll file.
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

You cannot configure a PowerShell connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
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.

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
`operationScriptFileName`	`String`	`C:/openidm/AD/ADCreate.ps1`,
The full path to the script that implements the corresponding OpenICF operation.
`VariablesPrefix`	`String`	`Connector`
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)
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`
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`
If `true`, the connector leverages the PowerShell RunSpace Pool.
`MaxInterpretersPoolSize`	`Integer`	`5`
The maximum size of the interpreter pool.
`MinInterpretersPoolSize`	`Integer`	`1`
The minimum size of the interpreter pool.
`PoolCleanupInterval`	`Double`	`60`
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`
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`
The attribute on the resource that contains the object `__UID__`.
`NameAttributeName`	`String`	`DistinguishedName`
The attribute on the resource that contains the object `__NAME__`.
`PsModulesToImport`	`Array`	`["ActiveDirectory","C:/openidm/samples/scripted-powershell-with-ad/tools/ADSISearch.psm1"]`
An array of additional PowerShell modules that the connector must import.
`Host`	`String`	`ad.example.com`
The host name or IP address of the Active Directory server.
`Port`	`Integer`	`null`
The port number on which the remote resource listens for connections.
`Login`	`String`	`""`
The user account in the remote resource that is used for the connection.
`Password`	`String`	`null`
The password of the user account that is used for the connection.
`CustomProperties`	`Array`	`[ ]`
An array of Strings to define custom configuration properties. Each property takes the format `"name=value"`. For example: "configurationProperties" : { ... "CustomProperties" : ["baseContext = CN=Users,DC=example,DC=com" ], ... } The custom property can then be read from the PowerShell scripts as follows: $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?_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:

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:

"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&param1=value1&param2=value2"

You can also call it through the IDM script engine, as follows:

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:

"systemActions" : [
    {
        "scriptId" : "SetExchange",
        "actions" : [
            {
                "systemType" : ".*PowerShellConnector",
                "actionType" : "PowerShell",
                "actionSource" : "Set-Exchange $Connector.Arguments.dn"
            }
        ]
    }
]

Manage Azure AD Objects With the PowerShell Connector

Ping provides two sets of sample scripts to let you manage objects in Azure AD with 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. 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. For information on connecting to your Azure AD with this module, refer to the corresponding Microsoft documentation. 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

Install a .NET connector server on your Windows host. These steps assume a Windows hostname of windows-host.example.com.
On windows-host.example.com, install the PowerShell connector.

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

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
```
Whatever location you choose for the scripts will be referenced in your connector configuration (provisioner file).

Download the Azure AD scripts from the ForgeRock stash repository.

Download either the V1 or V2 scripts, depending on your Azure AD module, and place them in the scripts directory you created in the previous step:

ls C:\openidm\scripted-powershell-with-azure-ad\scripts
Directory: C:\openidm\scripted-powershell-with-azure-ad\scripts

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---          7/21/2020  4:00 AM      10965 AzureADCreate.ps1
-a---          7/21/2020  4:00 AM       3547 AzureADDelete.ps1
-a---          7/21/2020  4:00 AM       6952 AzureADSchema.ps1
-a---          7/21/2020  4:00 AM       8149 AzureADSearch.ps1
-a---          7/21/2020  4:00 AM       2465 AzureADTest.ps1
-a---          7/21/2020  4:00 AM      10840 AzureADUpdate.ps1

By default, Windows does not trust downloaded scripts. To be able to run the scripts, you might need to do the following:

Run the Unblock-File cmdlet. This cmdlet unblocks PowerShell script files that were downloaded from the Internet so that you can run them, regardless of the PowerShell execution policy.
Change the PowerShell execution policy to let you run the scripts.

In IDM, configure the connection to the .NET connector server.
In IDM, configure the PowerShell connector.

The ForgeRock stash repository includes a sample provisioner file for both versions of the scripts. Use those files 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

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/azureadpowershell?_action=test"
{
  "name": "azureadpowershell",
  "enabled": true,
  "config": "config/provisioner.openicf/azureadpowershell",
  "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. Indicates whether the property value is considered confidential, and therefore encrypted in IDM.

2. A list of operations in this column indicates that the property is required for those operations.

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

ICF 1.5.20.25