Requirements

All PowerShell connectors that are used for OpenIAM version 4.x support the following operating systems:

• Windows Server 2016
• Windows Server 2019
• Windows Server 2022

While older operating systems are supported, OpenIAM recommends using newer versions. Older operating systems will require the installation of additional dependencies. Please make sure that the following minimal dependencies have been met.

Basic requirements

Basic requirements should be checked before starting the PowerShell connector installation as they refer to basic OS components and hardware.

Hardware requirements

For demo/test scenarios the following minimum hardware requirements are recommended:

• 2 (v)CPU
• 4GB RAM
• 60 GB disk space

For production scenarios the following minimum hardware requirements must be met:

• 4 (v)CPU
• 8GB RAM
• 60 GB disk space

Please note that the RAM amount is mostly consumed during synchronization processes. For example, if you have 5000+ objects inside your managed system, then it is highly recommended to increase RAM to 16GB+.

Disk space is mostly consumed for storing logs when running in debug mode. If this mode is on, then you should monitor your disk usage. Running out of disk space will negatively impact the connector. During the installation process you will be asked if the connector should remove old logs while rotating. This will reduce the possibility of logs consuming extensive amounts of disk space. If disabled, please make sure that you take care of deleting old logs yourself or moving them to an appropriate location.

Please make sure that the OS has enough space for normal work and updates

Software requirements

• .NET Framework 4.8
• PowerShell 5.1

.NET Framework

If you are running Windows Server older than 2016 and are not sure which .NET Framework version you have, you can refer to Microsoft guide: How to: Determine which .NET Framework versions are installed. Or you can also install the newest .NET Framework 4.x

PowerShell

If you run Windows Server 2016 or later, PowerShell 5.1 is included by default and you don't need to check this dependency.

If you are running Windows Server older than 2016, you can check the PowerShell version by running the PowerShell command:

$PsVersionTable

Additional dependencies

PowerShell connectors use SQL CE 4.0 database to manage log records. You can read more about it at Microsoft® SQL Server® Compact 4.0 SP1 download page.

During the installation, the connector installer checks if the SQL CE 4.0 runtime is installed. If no runtime is detected, the connector will start this installation automatically, so no additional steps are required.

Multiple connectors installation

It is possible to host multiple OpenIAM PowerShell connectors on the same connector server. For example, you can run AD and Office365 connectors on the same machine at the same time.

Load balancing

For load balancing you can install two or more connectors of the same type on different servers. Each of them should use the same configuration settings. During runtime, requests will be split between the number of connectors installed.

Getting connection parameters with OpenIAM

Before you start the installation process you should know following parameters:

• Hostname or IP address of RabbitMQ server instance and make sure it can be reached from the connector server. Usually it is the same as the OpenIAM address
• Queue name

To get the queue name to specify during the installation process you need to log in to your OpenIAM webconsole -> Provisioning -> Connectors -> Select your connector -> copy 'Connector queue' parameter from this page, as shown on the image below.

Installation process

All connectors have a generic installation process, so the information below is suited for all OpenIAM PowerShell connectors. For this example we just randomly picked the AD connector for demonstration of installation steps.

The screenshot below demonstrates the initial connector installation window.

When you press Install, the installer will check for the SQL CE 4.0 SP1 dependency. If the dependency is not found during installation, then the installer will install SQL CE 4.0 SP1. If it is present, then the installer will skip this step and proceed with the installation.

During the installation step above, you will be asked to provide the connector installation location. By default it is C:\Connectors\ConnectorName. However, you may want to override it.

You will be asked to configure log settings. If you are installing the connector for the first time you may want to set debug mode on to be able to track what is happening on the connector side when you run requests from OpenIAM.

If debug mode is disabled only information and error messages will appear in logs. Normally it will be just one record per request indicating that the request was processed. So if it is not running in debug mode the connector does not consume much disk space. However, in debug mode the log records amount significantly grows.

If you select the Remove old logs option, the connector will automatically delete rotated log records.

After clicking Next you will be asked to configure the RabbitMQ connection to your OpenIAM instance.

• Connector name: this parameter is used for distinguishing this particular connector among other connectors of different types installed on the same machine. It is just a human-readable value that makes sense for you. It should not contain whitespaces however, because this name will be included to process names.
• RabbitMQ host: usually hostname or IP address of your OpenIAM instance. However, in different scenarios this may vary.
• Username: RabbitMQ connection username. By default: openiam
• Password: RabbitMQ connection password. By default: Password#51, however, this is usually changed after initial configuration.
• Queue: this parameter should be taken from the connector configuration page inside OpenIAM. It is described above.
• Port: by default 5672. However, this could be overridden by your configuration. Please make sure that this port is opened on the OpenIAM instance and the RabbitMQ service that listens to it. If you are running a Docker installation - please make sure that the port could be reached in Docker as well.
• Virtual host: by default 'openiam_connector'.

To be sure that you have specified RabbitMQ settings correctly please press the Test connection button. Please note that Test connection just tests connection to RabbitMQ itself - address, port, username and password, and it cannot verify if your queue is correctly set (because different connectors can use different queues). Please make sure that you have specified the queue parameter correctly, because this is a frequently made mistake during the installation according to our feedback.

After having done the above you can confirm your installation by pressing Install. This will finalize your connector installation.

Removing connector

OpenIAM PowerShell connectors are removed like any other Windows software by going to Control Panel -> Uninstall a program -> Select your connector -> Right click -> Uninstall.

When the connector installer removes the connector it leaves all logs, configs and all other files that were created during the runtime. If you do not need that data you can manually remove the connector folder after the connector was uninstalled from the operating system.

Updating connector

PowerShell connectors are updated using the reinstallation process. Following steps are used to update connectors that do not have customizations.

1. Backup your connector folder (you can compress and/or copy it to a safe location)
2. Uninstall the current connector
3. Remove the connector folder
4. Install the new connector using the same connection parameters that you specified during the previous installation

In case you have some customizations, you should check the connector version before updating. If your major version (first two numbers) are the same, most likely you can just use the same script files that you used before.

To check the connector version you should go to Control panel -> Uninstall a program. You will see the connector version at the same line where you see the connector as shown in the image below.

If you have any customizations in the connector you can first extract PowerShell files of the new connector (you can also use a test VM for the purpose of testing) and in case you made customizations yourself you can compare it with the new version. If the OpenIAM team has made customizations for you, you can contact OpenIAM support in case you are not sure.

RabbitMQ QueueType

Starting from version 4.2.1.9, OpenIAM uses 'quorum' QueueType for RabbitMQ communication that involves communication with connectors.

.NET/PS connectors use this value by default starting from 5.31.0.0 version and higher. However, this parameter was made configurable on a connector side to retain backward compatibility, so if anyone would need to use any .NET/PS connector of 5.31.0.0 version of higher with any OpenIAM version below 4.2.1.9, it is possible to open Connector.config inside connector folder and edit QueueType parameter by changing quorum type to classic.

Troubleshooting: checking that connector QueueType parameter inside Connector.config matches the one that exists on RabbitMQ side.