Installing PowerShell connectors

Requirements

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

  • Windows Server 2008 R2
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019

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

Basic requirements

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

Hardware requirements

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

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

For production scenarios following minimum hardware requirements must be met:

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

Please note that that 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 may should monitor your disk usage. Running out of the 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 OS has enough space for normal work and updates

Software requirements

  • .NET Framework 4.6.2
  • PowerShell 5.1

.NET Framework

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

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 newest .NET Framework 4.*

PowerShell

If you run Windows Server 2016 or upper, 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 PowerShell version by running 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 connector installer checks if SQL CE 4.0 runtime is installer. If no runtime detected 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 and this is supported scenario. For example, you can run AD and Office365 connector on the same machine at the same time.

noteNote: Two connectors of same type cannot be installed on the same machine out of the box. So, for example, you cannot run 2 AD connectors on the same connector server by default.

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 the 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 could be reached from connector server. Usually it is the same as 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, like shown on the image below.

Getting RabbitMQ queue from webconsole

Installation process

All connectors have generic installation process, so the information below suits for all OpenIAM PowerShell connectors, we just randomly picked AD connector for demonstration of installation steps.

Below screenshot demonstrates initial connector installation window.

Initial PowerShell connector installation window

When you press "Install", the installer will check for the SQL CE 4.0 SP1 dependency. 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.

PowerShell connector destination folder selection

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.

PowerShell connector log configuration screen

You will be asked to configure log settings. If you are installing connector for the first time you may want to set debug mode on - to be able to track what happens on 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 1 record per request indicating that request was processed. So if not running debug mode connector does not consume much disk space. However, in debug mode log records amount significantly grows.

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

After pressing next you will be asked to configure RabbitMQ connection to your OpenIAM instance.

PowerShell connector RabbitMQ configuration

  • 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 the process names.
  • RabbitMQ host - usually hostname or IP address of your OpenIAM instance. However, in different scenarios may vary.
  • Username - RabbitMQ connection username. By default: openiam
  • Password - RabbitMQ connection password. By default: Password#51, however usually changed after initial configuration
  • Queue - this parameter should be taken from connector configuration page inside OpenIAM. Is described above.
  • Port - by default 5672, however could be overridden by your configuration. Please make sure that this port is opened on OpenIAM instance and RabbitMQ service listens to it. If you are running docker installation - please make sure that you that consequent 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 '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), so please make sure that you specified queue parameter correctly, because this is one of frequently done mistakes during the installation, according to our feedbacks.

Getting RabbitMQ queue from webconsole

After having specified 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 connector installer removes connector it leaves all logs, configs and all other files that were created during the runtime. If you do not need those data you can manually remove connector folder after connector was uninstalled from the operating system.

Updating connector

PowerShell connectors are updated using 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 so some safe location)
  2. Uninstall current connector
  3. Remove connector folder
  4. Install new connector using the same connection parameters that you specified during the previous installation

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

To check connector version you should go to Control panel -> Uninstall a program -> You will see connctor version at the same line where you see your connector. Like on the image below.

Checking PowerShell connector version

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