Differences

This shows you the differences between two versions of the page.

--- devel:documentation:systems:dev:winrm_connector [2019/06/11 13:10]
kucerar config + schema
+++ devel:documentation:systems:dev:winrm_connector [2019/07/10 09:55]
kucerar log rotation
@@ Line 1: / Line 1: @@
 ====== WinRM Connector ======
-This 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.
+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.
-<note important>Work in progress. This page is not complete!</note>
 Connector is based on Connid CMD connector. We made fork of CMD connector version 0.4-SNAPSHOT.
@@ Line 20: / Line 18: @@
 system you can just implement scripts yourself. As a template you can use existing python + ps scripts.
-Powershell scripts are in subfolders.
+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
@@ Line 38: / Line 36: @@
 ===== 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 ===
@@ Line 84: / Line 84: @@
   * \_\_PASSWORD\_\_
 You need to create other attributes manually based on the system which you want to connect and you needs.
+===== 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 =====
+==== python ====
+Python scripts should start with these two lines:
+<code>#!/usr/bin/env python
+# -*- coding: utf-8 -*-</code>
+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.
+<code>
+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"))
+</code>
+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.
+===== Installation =====
+For using this connector you need to install a few things which is needed.
+  * Install python, tested version is 2.7
+  * Install pip for managing Python packages - for linux use package managers based on you distribution and install package python-pip. If you are using windows pip will be installed together with python if you use official installator.
+  * Install pywinrm and dependencies. You can follow official guide https://github.com/diyan/pywinrm Just don't forget to install additional packages if you want use Kerberos or CredSSP authentication. If you are using windows you need to execute only the commands for pip, you don't need to install other system dependencies.
+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's recommended to use it.
+<note>Configure log rotation for connector server log file</note>
+You can download whole bundle with prepared and tested connector server here:<note important>It's not released to public yet</note>
+Or you can follow this guide and prepare the connector server yourself if you want.
+This connector is tested in java connector server 1.4.5.1 https://connid.atlassian.net/wiki/spaces/BASE/pages/360458/Downloads#Downloads-JavaConnectorServer
+and with connector-framework 1.4.3.0
+Next you will need to add these libraries into lib folder of the connector server:
+  * jackson-annotations-2.9.8
+  * jackson-core-2.9.8
+  * jackson-databind-2.9.8
+You will probably need to add these libs into classpath in ConnectorServer.sh or ConnectorServer.bat it depends on your OS.
+Now you can put winrm-connector-1.0.0.jar to the bundles folder inside connector server and you can start it.
+Next thing which you need to do is configure WinRM on windows server or check if WinRM is accessible. You can follow steps from out [[tutorial:adm:configuration_-_winrm|tutorial]]