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, MS 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 on the GitHub.

OpenIDM includes Active Directory and Azure sample scripts for the PowerShell connector that can help you get started with this toolkit. For more information, see "Samples That Use the PowerShell Connector Toolkit to Create Scripted Connectors" in the Samples Guide.

The sample scripts illustrate the following scenarios:

  • Synchronization of users between Windows AD DS and OpenIDM.

  • Synchronization of users between Windows Azure AD and OpenIDM.

Before You Start

To implement the scripted PowerShell connector, you need to 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, follow the instructions in "Installing and Configuring a .NET Connector Server" in the Integrator’s Guide.

  • PowerShell version 2.0 or above. The PowerShell Connector Toolkit is not bundled with OpenIDM, but is available on the GitHub. To install the connector, download the archive (mspowershell-connector-1.5.0.0.zip) and extract the MsPowerShell.Connector.dll to the same directory where the Connector Server (ConnectorServerService.exe or the legacy version ConnectorServer.exe) is located.

If you’re running a supported version of Microsoft Windows Server, you should already meet these requirements.

Setting Up 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 that .NET connector server on the same host on which the Windows PowerShell module is installed.

    For instructions on installing the .NET connector server, see "Installing and Configuring a .NET Connector Server" in the Integrator’s Guide.

  2. Configure OpenIDM to connect to the .NET connector server.

    To do so, copy the remote connector provisioner file from the openidm\samples\provisioners directory to your project’s conf\ directory, and edit the file to match your configuration.

    PS C:\ cd \path\to\openidm
PS C:\path\to\openidm cp samples\provisioners\provisioner.openicf.connectorinfoprovider.json conf

    For instructions on editing this file, see "Configuring OpenIDM to Connect to the .NET Connector Server" in the Integrator’s Guide.

  3. Download the PowerShell Connector Toolkit archive (mspowershell-connector-1.5.0.0.zip) from the GitHub.

    Extract the archive and move the MsPowerShell.Connector.dll to the folder in which the connector server application executable files (ConnectorServerService.exe and the legacy ConnectorServer.exe) are located.

  4. OpenIDM includes PowerShell scripts in openidm\samples subdirectories, including powershell2AD/ for Active Directory, and powershell2AzureAD for Azure AD. Copy these scripts to the host on which the .NET connector server is installed.

    The location of the scripts must be referenced in your connector configuration file, for example:

    "CreateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADCreate.ps1",
...

  5. Copy the sample connector configuration for the PowerShell connector from the samples\provisioners directory to your project’s conf directory.

    OpenIDM includes two sample PowerShell connector configurations:

    • Active Directory: provisioner.openicf-adpowershell.json

    • Azure AD: provisioner.openicf-azureadpowershell.json

    Each sample connector configuration file points to scripts in a specific directory. You may need to change them to match your deployment. If you’re connecting to a remote system such as Azure AD, you should also specify the Host and Port for your .NET server, as well as authentication information for your remote Azure AD deployment.

    +

    "configurationProperties" : {
    ...
    "CreateScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADCreate.ps1",
    "DeleteScriptFileName" : "C:/openidm/samples/powershell2AD/tools/ADDelete.ps1",
    ...
    "Host" : "[substitute Hostname or IP Address]",
    "Port" : [substitute port number],
    "Login" : "[substitute Windows Server auth]",
    "Password" : "[substitute password]",
    ...
},

    +

    In provisioner files, the OpenICF framework requires the path to use forward slash characters and not the backslash characters that you would expect in a Windows path.

Testing the PowerShell Connector

Start OpenIDM with the configuration for your PowerShell connector project.

The following tests assume that the configuration is in the default path/to/openidm directory. If your PowerShell project is in a different directory, use the startup command with the -p option to point to that directory.

$ cd path/to/openidm
$ ./startup.sh

Confirming the Connector Configuration

To test that the PowerShell connector has been configured correctly, run the following REST call:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request POST \
 "http://localhost:8080/openidm/system?_action=test"
{
  "name" : "azureadpowershell",
  "enabled" : true,
  "config" : "config/provisioner.openicf/azureadpowershell",
  "objectTypes" : [ "__ALL__", "group", "account ],
  "connectorRef" : {
    "connectorName" : "Org.Forgerock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
    "bundleName" : "MsPowerShell.Connector",
    "bundleVersion" : "[1.4.3.0,2.0.0.0)"
  },
  "displayName" : "PowerShell Connector",
  "ok" : true
}

The displayed output demonstrates a successful configuration of an Azure AD connector.

When you run this test, you should also see a log entry associated with the .NET connector server, in the logs/ subdirectory 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 OpenIDM queries, including query-all-ids and _queryFilter

With the following command, you can retrieve a list of existing users on an Azure AD system. You can also use any system-enabled filter, such as those described in "Presence Expressions" in the Integrator’s Guide.

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
 "http://localhost:8080/openidm/system/azureadpowershell/account?_queryId=query-all-ids"

Creating With the Connector

You can use the connector to create new users or groups on the target system, based options listed in the relevant provisioner.openicf-* configuration file.

For example, the following command creates a new user on a remote Azure AD instance:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request POST \
--header "content-type: application/json" \
--data '{
    "PasswordNeverExpires": false,
    "AlternateEmailAddresses": ["Robert.Smith@example.com"],
    "LastName": "Smith",
    "PreferredLanguage": "en-US",
    "FirstName": "Robert",
    "UserPrincipalName": "Robert.Smith@example.onmicrosoft.com",
    "DisplayName": "Robert Smith"
}' \
"http://localhost:8080/openidm/system/azureadpowershell/account?_action=create"

Updating With the Connector

The PowerShell scripts associated with update functionality support changes to the following properties:

  • Password

  • Principal Name

  • License

  • Common user attributes

As an example, you could use the following command to change the password for the user with the noted _id:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request PATCH \
--header "content-type: application/json" \
--data '{
    "operation": "replace",
    "Field": "__PASSWORD__",
    "value": "Passw1rd"
}' \
"http://localhost:8080/openidm/system/azureadpowershell/account/1d4c9276-6937-4d9e-9c60-67e8b4207f4e"

Deleting With the Connector

You can use the PowerShell connector to delete user and group objects. As an example, the following command deletes one user from an Azure AD deployment, based on their _id:

$ curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request DELETE \
"http://localhost:8080/openidm/system/azureadpowershell/account/1d4c9276-6937-4d9e-9c60-67e8b4207f4e"