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.

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.

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:

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

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.

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.

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.