PowerShell Connector Toolkit

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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 IDM 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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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 IDM 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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

    Note

    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.

    This table describes the configuration properties:

    PropertyTypeExampleEncrypted [a] Required [b]
    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

    [a] Indicates whether the property value is considered confidential, and therefore encrypted in IDM.

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

Test the PowerShell Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

These examples show you how to test that the connector is configured correctly and operating as expected: 

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, you should also see a log entry associated with the .NET connector server, in the logs/ directory of that server.

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"

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"

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 "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"

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"

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 "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"})

Important

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

  3. On windows-host.example.com, install the Windows Azure AD Module that corresponds to the version of the scripts you are using.

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

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

    Note

    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 IDM, configure the connection to the .NET connector server.

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

  • 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 you see no response from this connector test, check your connector configuration and the connection to the .NET connector server.

Read a different version of :