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.

Note: 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": "MsPSGraphConnector",
  "LogLevel": 0,
  "IsSaveRequestEnabled": true,
  "IsRabbitMQEnabled": true,
  "IsStatusLogEnabled": false,
  "RabbitMQHost": "aipoclouddemo.openiam.com",
  "RabbitMQUsername": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAaauU57pNqUql2K8z7cfMEAQAAAACAAAAAAAQZgAAAAEAACAAAAD9Vt21IK2wvWTNM47GAyXaTQ2epJvUyzFWJj0SHYwGoQAAAAAOgAAAAAIAACAAAAAzFAXpoqQi6bT8qlkQhJduv3yIOJCH8q6gshY7jvIyTxAAAABmxTNXwdqiRgIk8CfFsEVkQAAAAAFcf6YJhkhN+in+t0kiNqQMK24bSF7fdTv+GCCBQ+c1gBEuoS2cIFMVpNcOtB5jkXpAGuN8/ernPSga2ZXx1Xs=",
  "RabbitMQPassword": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAaauU57pNqUql2K8z7cfMEAQAAAACAAAAAAAQZgAAAAEAACAAAAANvSMNp7vGCEve7PUlcR3A7XtlHeeXi+xhUWuo0CDLcQAAAAAOgAAAAAIAACAAAADaM2r+2bJVtxmdtaXd1aMQDOvto/TBM4ZtTvpCLOekPiAAAACCtZ5Hfs6s5OMRBbGkadX9H998RMTrB92Nhpjoq3lHsEAAAAB6fGgR/4YnW92Mv0svbT4F1Q/QZDBNokFq9BDN47nvtedK4jko8uZ9eSofLcUA2VCvuuscYi+TSvxPVMGn1xYa",
  "RabbitMQPort": 5672,
  "RabbitMQVhost": "enc:AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAAaauU57pNqUql2K8z7cfMEAQAAAACAAAAAAAQZgAAAAEAACAAAACKXn/U4uKm5rBVRww7sZF0HuOzChLwx+h8GVHd/+DbKwAAAAAOgAAAAAIAACAAAAAcz3RieV3WnaVq1FdZ45XGsbpRKzDIkg2rk1b32Yk/6zAAAAAhxXUSv2Wvq1QU41EYXlrwdzcZFMD+mvgG/guXIM9vnCgdnwHs1Ztp33pOXHRxOzJAAAAATTnhbX/FFQWIkXFexqwfW+EKiENLofI2EEb3tS6R1T1NwMoOuqEWcU8ILiLwHiAE4PVLRNrdBCrnpJIU8aCNmg==",
  "RabbitMQQueues": [
    {
      "RabbitMQReceiveQueue": "RemoteConnector_ 402_Request",
      "RabbitMQResponseQueue": "RemoteConnector_ 402_Response",
      "Concurrency": 1,
      "QueueType": "quorum"
    }
  ],
  "ExecutionTimeoutMin": 60,
  "IsTLSEnabled": false,
  "LogSize": 256,
  "RequestRunnerPath": \\Runners\\PSClassic\\ConnectorRequestRunner.exe,
  "SearchResponseBatchSize": 1000000,
  "LogSearchResponses": false,
  "IsCleanupTaskActive": false,
  "FlushTimer": 3,
  "LogDBType": "SQLite",
  "LogDBConnectionString": "Data Source=C:\\Connectors\\MsPSGraphConnector\\Log.db",
  "DisableManSysHealthcheckRequests": false
}

The table below describes each configuration option.

Note: You will need to have administrator privileges to be able to save this configuration after changes are made.

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.0.0.0 – 5.31.0.0 use SQL CE 4.0 format.
• PowerShell connectors version 5.32.0.0 and later use SQLite log database by default.

It's important to use a compatible database viewer.

Important note: Starting from the 5.32.0.0 version we stopped supporting SQL Compact Edition and moved to SQLite database by default. You can continue using LinqPad for browsing logs, but you have to add a driver to support SQLite databases. The steps to do it are shown in the screenshots below.

Viewing log database

By default, all .NET/PowerShell connectors save logs in SQLite database, so any compatible viewer could be used to open and view log database. Example of using one of the viewers was given in a section above. Below, there are few example of queries that could be used for finding and viewing logs:

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

Checking the connector version

It is recommended to use the latest version of the connector. All of .NET/PS connectors are backwards compatible, so there won't be any issue with using the latest connector version with OpenIAM 4.2.0.

For checking your current .NET/PS connector version.

If connector in not installed:

1. Right click the installer file and select Properties.
2. In the window opened, find Details section, as shown below.

If connector is installed:

1. Go to Control panel > Programs > Programs and Features
2. Find AD Connector and in the list on the right there will be a version of the connector installed, as shown below.