Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
devel:documentation:adm:systems:winrm_ad_connector [2019/09/19 05:28]
kucerar fixes, added more info to installation part
devel:documentation:adm:systems:winrm_ad_connector [2020/05/25 12:34]
kucerar Versions and compatibility
Line 5: Line 5:
  
 Typical use cases for this combined connector are: Typical use cases for this combined connector are:
-  * Management of home directories - User is created via AD connector and home directory is created by WinRM Connector (powershell)+  * Management of home directories - User is created via AD connector and home directory is created by WinRM Connector (powershell). Owner of home directory can be set only locally.
   * Management of o365   * Management of o365
   * Management of Exchange   * Management of Exchange
Line 44: Line 44:
 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. 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 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 [[devel:documentation:systems:dev:how_to_write_scripts_for_winrm_ad_connector|special parametr]]
  
 Then in folder "scripts" you can find python script, which is wrapper for pywinrm client - https://github.com/diyan/pywinrm Then in folder "scripts" you can find python script, which is wrapper for pywinrm client - https://github.com/diyan/pywinrm
Line 80: Line 80:
   * Write powershell scripts, which will be performing desired operations on MS server (CREATE, UPDATE, ...)   * Write powershell scripts, which will be performing desired operations on MS server (CREATE, UPDATE, ...)
   * Write python scripts that transform data from ConId API to powershell script (examples in GIT repository)   * Write python scripts that transform data from ConId API to powershell script (examples in GIT repository)
 +
 +====== Version and compatibility ======
 +  * 1.0.0 - IdM 9.x and above
 +  * 1.0.1 - IdM 9.x and above
 +  * 1.0.2 - IdM 9.x and above
 +Cross domain feature available:
 +  * 1.0.3 - IdM LTS 9.7.x with Extras module 1.8.1
 +  * 1.0.4 - IdM 10.3.0 and above
 +
 +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 ===== ===== Provisioning =====
Line 101: Line 111:
  
 ===== Scripts ===== ===== Scripts =====
 +
 +For more information about how to write scripts, follow [[devel:documentation:systems:dev:how_to_write_scripts_for_winrm_ad_connector|How to write scripts for WinRM + AD Connector]]
 +
 ==== python ==== ==== python ====
 Python scripts should start with these two lines: Python scripts should start with these two lines:
Line 118: Line 131:
 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. 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.
  
 +<note tip>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.</note> 
 +<note tip>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</note>
 ===== Installation ===== ===== Installation =====
 For using WinRM part of this connector you need to install a few things which is needed, otherwise you can skip these steps. For using WinRM part of this connector you need to install a few things which is needed, otherwise you can skip these steps.
Line 125: Line 139:
   * 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.   * 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 tip>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 userThis 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: 
 +<code> 
 +su - connector-server 
 +pip install --user pywinrm
  
-<note>Configure log rotation for connector server log file</note> +#those only if you need them 
-You can download whole bundle with prepared and tested connector server https://git.bcvsolutions.eu/modules/connector-server/tree/develop +pip install --user pywinrm[kerberos] 
-<note important>It's private at this time</note> +pip install --user pywinrm[credssp]
- +
-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. +
- +
-Next it's good to do some more configuration as setting new password for connector server and create new user under which the connector server will be started. +
- +
-For setting new password for you remote connector use +
-<code> +
-./bin/ConnectorServer.sh -setKey -key yourKey -properties conf/connectorserver.properties+
 </code> </code>
 +</note>
  
 +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.
  
-If you want to be able to run connector server as a service follow next steps +  - Follow [[devel:documentation:adm:systems:connectors:remote_server|this howto]] to install remote connector server as a service. 
- +  Put ''winrm-ad-connector-1.0.1.jar'' to the ''bundles'' folder inside connector server installation and restart the connector server. 
-<code> +  Put CA certificate to WinRM server in this file inside connector server installation ''certs/winrm\_ca.pem''. For certificates use PEM format
-# create user which we run the connector server +  Put CA certificate to AD servers in the [[devel:documentation:adm:systems:connectors:remote_server#configuring_ssl_truststore |Java truststore]] created in this file in the connector server - ''conf/truststore.jks''. (How to get CA to AD server? [[https://proj.bcvsolutions.eu/kb/doku.php?id=operacni_systemy:skripty#stazeni_certifikatu_serveru_a_vlozeni_do_idm|Internal guide]] FIXME move to wiki) 
-useradd connector-server +
- +
-#create file +
-/etc/systemd/system/java-connector-server.service +
- +
-# content of the file, change path according where you have your connector server +
-[Unit] +
-Description=Java Connector Server Service +
-[Service] +
-User=connector-server +
-WorkingDirectory=/opt/connid-connector-server +
-ExecStart=/bin/bash /opt/connid-connector-server/bin/ConnectorServer.sh -run -properties /opt/connid-connector-server/conf/connectorserver.properties +
-SuccessExitStatus=143 +
-[Install] +
-WantedBy=multi-user.target +
- +
-# Reload and enable deamon +
-systemctl daemon-reload +
-systemctl enable java-connector-server +
- +
-Use this to start/stop/status +
-systemctl start java-connector-server +
-systemctl stop java-connector-server +
-systemctl status java-connector-server +
-</code> +
- +
-Now you can put winrm-ad-connector-1.0.1.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]]+  - Configure WinRM on windows server or check if WinRM is accessible. You can follow steps from our [[tutorial:adm:configuration_-_winrm|tutorial]].
  
 ===== Configuration ===== ===== Configuration =====
Line 235: Line 211:
 You can configure the order of connectors. Default behavior is that AD connector is first. You can configure the order of connectors. Default behavior is that AD connector is first.
 {{ :devel:documentation:systems:dev:winrm_ad_order.png?nolink&400 |}} {{ :devel:documentation:systems:dev:winrm_ad_order.png?nolink&400 |}}
 +<note>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!).</note>
  • by kotynekv