Using PowerShell connectors

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

Working with 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 connector folder.

If are using v4 of the connectors, then the configuration file can be found at: *%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 we will describe how to work with 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 config file no connector restart is required and changes are applied on-the-fly.

Connector configuration format

This is a sample of a 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.
Parameter nameDescription
ConnectorNameName that was given to this connector during the installation. This name could be found inside 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 connector does with request step-by-step, but it is verbose and may consume a significant disk space if it utilized for a long period of time. Adjust log level according to your needs.
IsSaveRequestEnabledEnables or disables the saving of requests 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. Its equivalent to putting 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 response 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. Is 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 processes 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 for existing for a worker process. If this amount of time is reached, but worker process is still processing 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 OpenIAM connector installer performs the installation, it encrypts sensitive data like username, password, vhost by default. If you would like to get a new encrypted value to replace existing one you should open 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 want just 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 connector configuration file. Please pay attention that connector configuration file format is maintain. 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 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 its not possible to see the connector logs in OpenIAM. For example, if the connector loses connection with OpenIAM. In such cases it is very useful to check connector logs to determine what went wrong.

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

Log format

The Connector log file is located inside 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.

Its 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 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 user to this database.

To connect to log the 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 of 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 service the itself; in this situation the Log.db will not be very useful, because service was not able to start normally. However, you will be able to see messages in 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 example of how connector restart looks in Windows Event Viewer.

EventViewer logs for PowerShell connector

Simulation mode

PowerShell connectors support a Simulation mode which is a powerful tool that can help to troubleshoot and to 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 per each OpenIAM request. That JSON file contains request parameters that represent request. Having this file, you can trigger connector process this 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 request again you need to manually edit the file and set actual password properties instead of *.

When you have done above, to trigger request re-running you should open Connector.ps1, which is located inside your connector folder and edit the lines. We recommend to use PowerShell ISE native Windows tool for editing 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 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