Using PowerShell connectors

This page covers common use cases and they are applicable to all OpenIAM PowerShell connectors.

Working with the connector configuration

Sometimes there is a need to change the connector configuration. These changes can include connection parameters, enabling debug mode, etc. Starting with v5 of the OpenIAM .NET connectors, the configuration file is stored inside the connector folder.

If you are using v4 of the connectors, then the configuration file can be found in *%programdata%/OpenIAM/* where the config file name is based on the connector name that was given to the connector during the installation process.

noteNote: This document will describe how to work with the config file with connector version 5.

The config file, which is called Connector.config, is stored in a JSON format. The file is monitored by the connector service which detects changes that were done. So when you change the config file no connector restart is required and changes are applied on-the-fly.

Connector configuration format

This is a sample configuration file:

{
"ConnectorName": "ADConnectorV5",
"LogLevel": 0,
"IsSaveRequestEnabled": true,
"IsRabbitMQEnabled": true,
"IsBroadcastStatusResponseEnabled": true,
"RabbitMQHost": "demo.openiam.com",
"RabbitMQUsername": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAIz8dJj3lakqOMP3ss9ovrwQAAAACAAAAAAAQZgAAAAEAACAAAAAmm5KR+D5Gq7GTUCIKMAEjHe7mxSlqeqLfMUQ9NQa07gAAAAAOgAAAAAIAACAAAACXpbpeJOgmvqDqgHiytWGtZa+S1a07i7USJ2knEyQrvRAAAADH3BJSYePz3Wj8xB65JYebQAAAAH6af+NylpUNQr/vnnt1v4JrUD0hE/x3WO2l4gkHcJx2tf2eEHbYvbIQFny7XpRS6aYsiaugfMl4DdjEh3rFigY=",
"RabbitMQPassword": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAIz8dJj3lakqOMP3ss9ovrwQAAAACAAAAAAADZgAAwAAAABAAAABWrOJ9jmuS6v9684+qW01kAAAAAASAAACgAAAAEAAAAF6avDFT+usxBCNM21KV2qIYAAAAeRkA7JGFNRxc0ta9H/c8bBzVY1cfz0qJFAAAABknf3jqnpfF/iSeJdAr3Va16JZi",
"RabbitMQPort": 5672,
"RabbitMQVhost": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAIz8dJj3lakqOMP3ss9ovrwQAAAACAAAAAAAQZgAAAAEAACAAAABcS2di1bbt+zKreedyouGgOyUCbOwakqT5xwbux5BmsgAAAAAOgAAAAAIAACAAAAAZbMAftGTSFONU9qSVEgq30eVSNtCcxRaYGK1vVFxNcDAAAABijoX5n1zzFcAci2cadhn9+xPsGJ7embMf7tKCJ4sjzTywpFZwdKH7xt2JqXYjnUBAAAAAfNB/kVYFLnMRWwjnHdTt0g0FAXrwLz01X24vKPIE2bKKo0oeEe2ZvkH1cy6QECV/mlb1aSV3eNa4rLzeE6aA3A==",
"RabbitMQReceiveQueue": "RemoteConnector_1_Request",
"RabbitMQResponseQueue": "RemoteConnector_1_Response",
"Concurrency": 1,
"ExecutionTimeoutMin": 10
}

The table below describes each configuration option.

noteNote: You will need to have administrator privileges to be able to save this configuration after changes are made.
Parameter nameDescription
ConnectorNameName that was given to this connector during the installation. This name could be found inside the log database and the Windows System Event Viewer. The name of the connector can be used to distinguish what connector originated records, because there could be multiple connectors of different types installed on each server.
LogLevelIf set to 0, the connector will log all possible records. This is also called 'Debug' mode. You can set it to 0 when you are trying to figure out what the connector does with each request step-by-step, but it is verbose and may consume significant disk space if utilized for a long period of time. Adjust log level according to your needs.
IsSaveRequestEnabledEnables or disables the saving of request data to the simulation folder (Simulation mode will be described in detail later in this document)
IsRabbitMQEnabledSetting this to false will disconnect the connector from the OpenIAM service bus. It's equivalent to putting the connector on hold without stopping it as a service.
IsBroadcastStatusResponseEnabledEnables or disables broadcast responses. Such requests are sent by OpenIAM to 'ping' connectors to perform a health check. Normally, OpenIAM sends such broadcast requests once per minute and connectors that answer those are marked as 'Active' on the managed systems dashboard. In normal scenarios it is not recommended to change this setting.
RabbitMQHostThe hostname or IP address where the RabbitMQ message bus is located. Usually, this should be the same as the IP address or hostname of the OpenIAM service.
RabbitMQUsernameUsername for connecting to RabbitMQ. By default, this value is encrypted. However, it can also be used un-encrypted. Changing this setting in an encrypted format will be described later in this document.
RabbitMQPasswordPassword for connecting to RabbitMQ. By default, this value is encrypted. However, it can also be used un-encrypted. Changing this setting in an encrypted format will be described later in this document.
RabbitMQPortPort for connecting to RabbitMQ. 5672 is used by default.
RabbitMQVhostVirtual host for connecting to RabbitMQ. It's encrypted by default. Changing this setting will be described later in this document.
RabbitMQReceiveQueueThis queue is used by the connector to receive requests from OpenIAM. This value can be taken from the OpenIAM connector configuration page in the webconsole + _Request
RabbitMQResponseQueueThis queue is used by the connector to send responses back to OpenIAM. This value can be taken from the OpenIAM connector configuration page in the webconsole + _Response
ConcurrencySets number of requests from OpenIAM that could be processed at a time. Each request is being handled by a separate worker process that is disposed of after the request has been completed. The number which is set in this parameter represents the number of worker processes that can run at a time.
ExecutionTimeoutMinMaximum time in minutes existing for a worker process. If this amount of time is reached but the worker process is still processing the request it will be killed.

Working with encrypted parameters

The OpenIAM connector server should be well-secured and access should be restricted to a limited number of users. To ensure security, critical OpenIAM configuration parameters in the config file are encrypted using the machine key. This means that this string could be decrypted only on the same connector machine.

When the OpenIAM connector installer performs the installation, it encrypts sensitive data like username, password and vhost by default. If you would like to get a new encrypted value to replace an existing one you should open the PowerShell console on the same machine where the connector has been installed and run the following commands:

Set-Location 'Your connector folder address'
Import-Module .\CryptCmdlet.dll
ConvertTo-EncryptedString -StringToEnctypt 'SomeValue' | clip

Those commands will encrypt the SomeValue string and copy the output to your clipboard (if you just want to display it, remove | clip from the end of the last line). Subsequently, if you would like to encrypt username, you should replace some value with the username. Next, you will need to replace it inside the connector configuration file. Please pay attention to ensure that the connector configuration file format is maintained. It uses a JSON format and you must ensure that starting and terminating quotes (") are in the right place.

Working with logs

Each request that is sent from OpenIAM contains the parentAuditLogId parameter which allows OpenIAM to track the request result and show it in the OpenIAM audit logs. All errors returned from connectors are seen in OpenIAM audit logs.

However, there may be situations where viewing it is not possible, such as when the connector loses connection with OpenIAM. In such cases it is very useful to check the connector logs to determine what went wrong.

These local connector logs can be very helpful for troubleshooting and understanding how the connector works.

Log format

The connector log file is located inside the connector folder and is called Log.db.

  • PowerShell connectors version 4.x use SQL CE 3.5 database log format
  • PowerShell connectors version 5.x use SQL CE 4.0 format.

It's important to use a compatible database viewer.

Viewing log database

In our examples we will work with LinqPad which is a free utility. Please note that by default only users with LocalSystem/Admin privileges can change content of the connector folder. To extend this to other users, you will need to grant write access to this database to the appropriate users or groups of users to this database.

To connect to the log database, you need to start LinqPad and press 'Add connection' like shown on the picture below:

Adding connection to log database

Next, you will need to specify database type and select a Log.db file location.

Establishing a database connection

After this you will see your log database connection on the left side of your screen and you will be able to interact with it like with any normal database.

LinqPad supports SQL and C# expressions. A few examples are provided below.

  • Query logs for provisioning some user
SELECT * FROM Logs WHERE IdentityValue = 'SomeUserIdentity' ORDER BY ID DESC
  • Query logs for certain request ID
SELECT * FROM Logs WHERE RequestID = '5583cf9a-abdd-42cb-aa50-b433458c4cfb' ORDER BY ID DESC

Windows Event Viewer

Important messages may also be sent by the connector to the Windows Event Viewer. It may include various situations like problems with starting the service itself. In this situation the Log.db will not be very useful, because the service was not able to start normally. However, you will be able to see messages in the Windows Event Viewer. Messages can be found in Windows Logs -> Application. Messages can be found by source OpenIAM Connector Service and the ConnectorName that was provided for the connector during installation. Below is an example of how a connector restart looks in the Windows Event Viewer.

EventViewer logs for PowerShell connector

Simulation mode

PowerShell connectors support a Simulation mode which is a powerful tool that can help troubleshoot and re-run certain requests.

By default, when you turn debug mode on and you have the IsSaveRequestEnabled config parameter enabled, the connector creates a JSON file for each request that is sent from OpenIAM to the AD connector. That JSON file contains request parameters that represent requests. Having this file, you can trigger the connector to process the request that was recorded in the file without listening to OpenIAM.

noteNote: For security reasons all properties related to passwords (containing this keyword) are masked with *. To re-run the request again you need to manually edit the file and set actual password properties instead of *.

When you have done the above, to trigger the request again you should open Connector.ps1, which is located inside your connector folder and edit the lines. We recommend to use the PowerShell ISE native Windows tool for editing the PowerShell files.

Below is the initial code snippet that we will modify.

[bool]$isReplayXMLSimulation = $false
if($isReplayXMLSimulation -eq $true)
{
Add-DbLog -Message "Restoring request from simulation. Connector folder is '$connectorFolder'" -RequestID $requestID -LogLevel 0 -MinLogLevel $minLogLevel
#load simulation content
$simulationFileName = 'filename.json'
$requestString = Restore-RequestString -ConnectorFolder $connectorFolder -FileName $simulationFileName
$connectorOperation = 'SAVE'
}
  1. Change $isReplayXMLSimulation to $true
  2. Set simulationFileName equal to your file name inside the Simulation folder (just filename needed, not the full path)
  3. Set connectorOperation type to the connectorOperation variable. Valid options include: SAVE, SEARCH, DELETE, RESET_PASSWORD, LOGIN, SUSPEND, RESUME, TEST

The newly modified version could look like:

[bool]$isReplayXMLSimulation = $true
if($isReplayXMLSimulation -eq $true)
{
Add-DbLog -Message "Restoring request from simulation. Connector folder is '$connectorFolder'" -RequestID $requestID -LogLevel 0 -MinLogLevel $minLogLevel
#load simulation content
$simulationFileName = 'SAVE-05_25_43_255.json'
$requestString = Restore-RequestString -ConnectorFolder $connectorFolder -FileName $simulationFileName
$connectorOperation = 'SAVE'
}

When you apply your changes, you can run and debug the PowerShell script using PowerShell ISE or any appropriate tool.

Debugging PowerShell connector