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 the requirements of your Microsoft Windows ecosystem. 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. Essentially, any task that can be performed with PowerShell can be executed through connectors based on this toolkit.

The PowerShell Connector Toolkit is available from the ForgeRock BackStage download site.

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). No sample scripts are bundled with the connector, but Identity Cloud customers have access to the Scripted REST connector source code at https://stash.forgerock.org/projects/OPENICF/repos/powershell-connector/browse. This repository includes sample scripts for all the ICF operations.

Before You Start

To implement a scripted PowerShell connector, you must install the following:

  • Microsoft .NET Framework 4.5 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 Set Up a .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 of the commands in this procedure require administrative privileges.

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

  2. Configure Identity Cloud to connect to the .NET connector server.

  3. Download the PowerShell Connector Toolkit archive (mspowershell-connector-1.4.7.0.zip ) from the ForgeRock BackStage download site.

    Extract the archive and move the MsPowerShell.Connector.dll to the folder in which the connector server application executable file (ConnectorServerService.exe ) is located.

  4. Download the sample scripts on the host on which the .NET connector server is installed.

    Reference the full path to the scripts in your connector configuration, for example:

    "CreateScriptFileName" : "C:/openidm/samples/scripted-powershell-with-ad/tools/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.

  2. Verify that at least the path to the scripts and the connection and authentication details are correct for your deployment.

    This table describes the configuration properties:

    PowerShell Connector Configuration
    Property Type Example Encrypted [1] Required [2]

    operationScriptFileName

    String

    C:/openidm/AD/ADCreate.ps1,

    No
    Yes

    The full path to the script that implements the corresponding OpenICF operation.

    VariablesPrefix

    String

    Connector

    No
    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)

    No
    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

    No
    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

    No
    No

    If true, the connector leverages the PowerShell RunSpace Pool.

    MaxInterpretersPoolSize

    Integer

    5

    No
    No

    The maximum size of the interpreter pool.

    MinInterpretersPoolSize

    Integer

    1

    No
    No

    The minimum size of the interpreter pool.

    PoolCleanupInterval

    Double

    60

    No
    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

    No
    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

    No
    No

    The attribute on the resource that contains the object +UID`.

    NameAttributeName

    String

    DistinguishedName

    No
    No

    The attribute on the resource that contains the object +NAME`.

    PsModulesToImport

    Array

    [ "ActiveDirectory", "C:/openidm/samples/scripted-powershell-with-ad/tools/ADSISearch.psm1"]

    No
    No

    An array of additional PowerShell modules that the connector must import.

    Host

    String

    ad.example.com

    No
    Yes

    The host name or IP address of the Active Directory server.

    Port

    Integer

    null
    No
    Yes

    The port number on which the remote resource listens for connections.

    Login

    String

    ""
    No
    Yes

    The user account in the remote resource that is used for the connection.

    Password

    String

    null
    Encrypted
    Yes

    The password of the user account that is used for the connection.

    CustomProperties

    Array

    [ ]
    No
    No

    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 that the connector is configured correctly and operating as expected:

Check the Connector Configuration
curl \
--header "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://tenant-name.forgeblocks.com/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, you should also see a log entry associated with the .NET connector server, in the logs/ directory of that server.

Create Users or Groups

This command creates a new user in Active Directory:

curl \
--header "Authorization: Bearer *token*" \
--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"
}' \
"https://tenant-name.forgeblocks.com/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 change the password for the user with the specified _id:

curl \
--header "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request PATCH \
--header "content-type: application/json" \
--data '{
  "operation": "replace",
  "Field": "password",
  "value": "Passw1rd"
}' \
"https://tenant-name.forgeblocks.com/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 "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://tenant-name.forgeblocks.com/openidm/system/adpowershell/account/1d4c9276-6937-4d9e-9c60-67e8b4207f4e"
Run Scripts Through the Connector

The runScriptOnConnector script lets you run an arbitrary script action through the connector. This script 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).

Arguments

A map of script arguments (this can be null).

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 "Authorization: Bearer *token*" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"https://tenant-name.forgeblocks.com/openidm/system/adpowershell?_action=script&scriptId=MyScript&param1=value1&param2=value2"

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

openidm.action("/system/adpowershell", "script", {}, {"scriptId": "MyScript", "param1": "value1", "param2": "value2"})

Because the action script is stored locally with Identity Cloud, 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 Identity Cloud 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

ForgeRock 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, see 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, see 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

  1. Install a .NET connector server 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.

    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 you see the following text on that tab:

    This file came from another computer and might be blocked to help protect this computer.

    Click the Unblock button 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.

  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

    Whatever location you choose for the scripts will be referenced in your connector configuration (provisioner file).

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

  3. In Identity Cloud, configure the connection to the .NET connector server.

  4. In Identity Cloud, 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

  1. Test that the connector has been configured correctly and can reach the Azure AD:

    curl \
    --header "Authorization: Bearer *token*" \
    --header "Accept-API-Version: resource=1.0" \
    --request POST \
    "https://tenant-name.forgeblocks.com/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 you see 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 Identity Cloud.
2. A list of operations in this column indicates that the property is required for those operations.