Table of Contents

WinRM + AD Connector

This connector is combining WinRM and AD connector into one. The main advantage of this is you can execute operation by AD connector or by WinRM connector or with both together in specified order.

General information

Typical use cases for this combined connector are:

Schema:

When you use this connector then in IdM you will has only one system and every user who is managed via this system will have only one account. For example if you want to manage home directories together with AD then user will have only one account and so when you create user, directory will be created to.

Theoretically you can use WinRM connector for home directories and AD connector for user management separately. You will have two system in IdM and user will have two accounts. But then you will have no control over the order of execution. And when you need to set some ACL permissions to the home directory the user must be created before.

When you want to execute some operation via both connectors and the first connector execution will failed then the execution by the second connector is not executed. You will see error in provisioning in IdM. In case where the second execution will fail you will see error in IdM again. Then when retry provisioning will kick in, IdM perform search to the end system again that mean if you want for example assign role in AD to user and then execute powershell for Exchange and the powershell execution will fail for some reason. Retry provisioning will know that the role is already assigned so nothing will happen via AD connector and only powershell will be executed.

WinRM Connector

This part is only what is supported by WinRM connector. AD connector has the same functionality as if you use the standalone version.

Windows Remote Management (WinRM) connector can be used to connect to basically to any system which can be managed via powershell commands or some specialized client which can be called from powershell.

Connector is based on Connid CMD connector. We made fork of CMD connector version 0.4-SNAPSHOT.

We implemented some features which were missing.

Where "NameOfSystem" is one of these following values Exchange, OpenLims, o365, homeDir (More systems will maybe come in future). If you want use this connector for another system you can just implement scripts yourself. As a template you can use existing python + ps scripts.

Powershell scripts are in subfolders. It's not only "normal" powershell script which contains the commands which we want to execute, but it must handle exceptions and in the case of search scripts the response should be in json format, so we can parse in connector a forward it to IdM. The risk of not catching exceptions can be that IdM will show operation as successful but it failed or the other way around.

All of these scripts logging into connector server log. All log messages are shown after powershell script is executed and the control is returned into connector. So it can see that the log is frozen if the powershell script will run some time. Disadvantage is, if your powershell script froze for real you will not see any log. This can happen for example if you execute some command which will wait for user input, but you can prevent this one by using special parametr

Then in folder "scripts" you can find python script, which is wrapper for pywinrm client - https://github.com/diyan/pywinrm which is used for connecting and executing PS scripts in windows server. You need to install first. In the link above there is a tutorial.

It's better to run it in connector server instead of directly adding dependency to your application(IdM). The reason for this is simple - better security. You can choose user with some limited permissions which will be used as the owner of connector server and then give him access to run only the scripts which you want.

It supports basic, ntlm, kerberos and credssp authentication schema for WinRM

It supports HTTP and HTTPS communication. HTTPS communication can be a little bit tricky to configure. You need the right certificate which is used in WinRM listener on Win server. Store the crt to the on the machine where this connector is running and for:
WinRM < 1.0.5 Edit winrm_wrapper.py to change the path to .pem certificate which is needed for HTTPS connection. 

p = winrm.protocol.Protocol(endpoint=endpoint,
                            transport=authentication,
                            username=user,
                            password=password,
                            ca_trust_path='/opt/connid-connector-server/certs/winrm_ca.pem')

WinRM >= 1.0.5 there is configuration field called "WinRM___CA trust path" - Path to certificate which will be used in HTTPS communication. E.g /path/to/file/crt.pem
Be sure you are using up to date winrm_wrapper.py otherwise this new config property don't work and you will be forced to use previous solution.

Schema generation

Connector is supporting basic schema generation. You will get these attributes:

You need to create other attributes manually based on the system which you want to connect and you needs.

Requirements

Here are some requirements needed in order to use winrm connector.

Version and compatibility

Cross domain feature available:

If you want to use IdM 10.0.0, 10.1.0 or 10.2.0 and be able to use cross domain functions you need to update IdM to 10.3.0, if you don't need cross domain feature and don't want to update IdM you can try to use connector 1.0.2

Provisioning

For objectClass GROUPS provisioning is not supported in current version.

For objectClass ACCOUNT, the connector is supporting these operations: CREATE, UPDATE, DELETE, SEARCH.

Synchronization

For ACCOUNT you need to use Reconciliation, normal synchronization is not supported in current version.

Supported operations

Object Operations
__ACCOUNT__ CREATE, UPDATE, DELETE, SEARCH
__GROUP__ NONE

Managing users groups

When you use this connector for some system where you need to manage groups for users (OpenLims). Attribute for roles must be called "roles" is schema definition. Then it's work in the same way as roles for AD. That's mean you need to create role in IdM which will have assigned this system and in mapping override attribute "roles" with value which the system accept. Strategy should be Merge or Authoritative merge

Scripts

For more information about how to write scripts, follow How to write scripts for WinRM + AD Connector

python

Python scripts should start with these two lines: 

#!/usr/bin/env python
# -*- coding: utf-8 -*-

The second line is important because in python 2.x default encoding is ASCII so if don't specify the encoding in python file then we will have problems with using diacritics. Then if we need to load powershell script into python and replace some params, It's recommended to open with encoding. 

import codecs
f = codecs.open(os.environ["script"], encoding='utf-8', mode='r') #os.environ["script"] is path to script which is send from IdM configuration
command = f.read()
command = command.replace("$firstName", winrm_wrapper.getParam("firstName"))

For getting parameter from environment you can use method in winrm_wrapper which will return value or empty string if the variable is not in environment. It will return value as unicode with utf-8 encoding

We are using encoding otherwise you will have problem with diacritics in powershell when you want to encode the powershell script before sending it via WinRM.

In windows system python was running in encoding cp1252 and I had to use command below to reconfigure to utf8. This command is available from python version 3.7 
sys.stdout.reconfigure(encoding='utf-8')
Update operation is a little bit trickier. In this script it'll be needed implementation of both create and update operations. Because of some reason there could be user, which already has account on AD, but does not have home directory. And if you need some additional attributes to create a home directory (e.g. for each department different folder), in update operation an attribute will not be normally send if value of the attribute was not changed.
For search and delete operations IdM only sends uid. So in this scripts you cannot use any other attributes. For example someone would want to rename home directory in delete script and leave it there for period of time as backup. But in this situation you can only add to home directory's name some static text

Installation

For using WinRM part of this connector you need to install a few things which is needed, otherwise you can skip these steps.

Better way to install python packages through pip is to not install them system-wide. Create user for the connector server (see later on this page) and install packages only for this user. This ensures stability (system-wide updates do not change versions, thus cannot break your connector) and isolation from the rest of the OS (pip does not accidentally break OS-provided libraries). To install what you need, just issue: 
su - connector-server
pip install --user pywinrm

#those only if you need them
pip install --user pywinrm[kerberos]
pip install --user pywinrm[credssp]

Now we have prepared the tool which is used by our connector. Next you need to install java connector server. Connector server is not mandatory but as we wrote in the first section it is strongly recommended.

Configuration

In configuration you have the option to configure AD connector and WinRM connector. So follow WinRM configuration below and AD configuration.

Connector has few settings which need to be configured before you used it.

If your connector server is running on Windows then you need to enter "python " before the actual path to script. E.g. "python C:\scripts\homeDir\testDir.py"

Create script

Path to Python create script

Powershell create script

Path to powershell create script which will be loaded into python and executed on Windows

Update script

Path to Python update script

Powershell update script

Path to powershell update script which will be loaded into python and executed on Windows

Search script

Path to Python search script

Powershell search script

Path to powershell search script which will be loaded into python and executed on Windows

Delete script

Path to Python delete script

Powershell delete script

Path to powershell delete script which will be loaded into python and executed on Windows

Test script

Path to Python test script

Endpoint

URL to the endpoint, where is WinRM accessible. Usually https://HOST:5986/wsman for HTTPS and http://HOST:5985/wsman for HTTP

Authentication schema

One from supported values - basic, ntlm, kerberos, credssp

User

Username for user which will be used for authentication to WinRM

Password

Password for this user

CA trust path

Path to certificate which will be used in HTTPS communication. E.g /path/to/file/crt.pem

Ignore CA validation

If you want to connect to WinRM without CA validation - Don't use in production, only for testing!

Then there are some other options which can be configured. You can configure which connector will be used for which operation. For example you can use AD + WinRM for create and only WinRM for delete, etc. You can configure the order of connectors. Default behavior is that AD connector is first.

Note that when you check both the AD and WinRM options for the Create / Update / Delete operation, the same type of operation is called in both connectors. For example, if one connector creates an object, the other connector tries to create it as well, then the operation ends up with an error because the object already exists (but the first connector does not rollback!).