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
devel:documentation:adm:systems:winrm_ad_connector [2021/11/22 07:29] – updated python version kucerardevel:documentation:adm:systems:winrm_ad_connector [2025/09/01 09:05] (current) – [Cross domain configuration] otmara
Line 15: Line 15:
 Schema: {{  ..:..:systems:dev:winrm_ad_schema.png?nolink&  }} Schema: {{  ..:..:systems:dev:winrm_ad_schema.png?nolink&  }}
  
-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.+When you use this connector then in IdM you will have 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. 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.+When you want to execute some operation via both connectors and the first connector execution fails then the execution by the second connector will not be executed. You will see error in provisioning in IdM. In case the second execution fails you will see error in IdM again. Then when retry provisioning kicks in, IdM performs search to the end system again, that means if you want for example assign role in AD to user and then execute powershell for Exchange and the powershell execution fails 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 ====== ====== WinRM Connector ======
Line 51: Line 51:
 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'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 basic, ntlm, kerberos and credssp authentication schema for WinRM. To use Kerberos, you need to have properly-configured ''/etc/krb5.conf''  in your system. (see https://doc.czechidm.com/doc-admin-guide/1.3/connector-server.html#_configuring_kerberos_support)
  
 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 <nowiki>winrm_wrapper.py</nowiki> to change the path to .pem certificate which is needed for HTTPS connection. 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 <nowiki>winrm_wrapper.py</nowiki> to change the path to .pem certificate which is needed for HTTPS connection.
Line 65: Line 65:
  
 **WinRM >= 1.0.5**  there is configuration field called <nowiki>"WinRM___CA trust path"</nowiki> - 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 <nowiki>winrm_wrapper.py</nowiki> otherwise this new config property don't work and you will be forced to use previous solution. **WinRM >= 1.0.5**  there is configuration field called <nowiki>"WinRM___CA trust path"</nowiki> - 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 <nowiki>winrm_wrapper.py</nowiki> otherwise this new config property don't work and you will be forced to use previous solution.
 +
  
 ===== Schema generation ===== ===== Schema generation =====
Line 100: Line 101:
   * 1.0.6 - IdM > 10.3.0 < 11.2.0   * 1.0.6 - IdM > 10.3.0 < 11.2.0
   * 1.0.7 - IdM 11.2.0 and above = CzechIdM supports cross domain. No need for extras module   * 1.0.7 - IdM 11.2.0 and above = CzechIdM supports cross domain. No need for extras module
 +  * 1.0.15 - IdM ??? and above = Cross domain provisioning works from AD connector itself, works for large numbers of groups
  
 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 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 151: Line 154:
 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 important>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</note>+<note important>When connector server is running on Windows all powershell scripts need to you Write-Output function instead of Write-Host</note> <note important>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</note>
  
 <code> <code>
Line 164: Line 167:
 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.
  
-  * Install python, tested versions are <del>2.7 </del> (this version is no longer supported by python so use 3.X), 3.6 and 3.9+  * Install python, tested versions are 3.6 and 3.9
   * 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 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|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|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.
Line 175: Line 178:
  
 #those only if you need them #those only if you need them
-pip install --user pywinrm[kerberos]+pip install --user pywinrm[kerberos] python-krb5ticket
 pip install --user pywinrm[credssp] pip install --user pywinrm[credssp]
  
Line 258: Line 261:
  
 If you want to connect to WinRM without CA validation - Don't use in production, only for testing! If you want to connect to WinRM without CA validation - Don't use in production, only for testing!
 +
 +=== Support AD CrossDomain Provisioning ===
 +
 +AD connector will be used to handle cross domain groups. If this is selected, the Use only WinRM for Groups checkbox must be unselected, otherwise the AD connector won't get the necessary data to do anything.
 +
 +=== Prohibit WinRMCrossDomainProvisioning ===
 +
 +WinRM won't be used for cross domains - this should be used alongside Support ADCrossDomainProvisioning.
  
 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. {{  ..:..:systems:dev:winrm_ad_config.png?nolink&400  }}You can configure the order of connectors. Default behavior is that AD connector is first. {{  ..:..: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> 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. {{  ..:..:systems:dev:winrm_ad_config.png?nolink&400  }}You can configure the order of connectors. Default behavior is that AD connector is first. {{  ..:..: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>
  
-=== Cross domain configuration ===+==== Cross domain configuration ==== 
 + 
 +\\ 
 +**<WRAP center round important 60%>\\ 
 +Principal must be in the form of [domain]\[name] (ZOO\Administrator) - using Distinguished Name from AD works for AD but not for winrm\\ 
 +</WRAP>** 
 + 
 +**<WRAP center round important 60%>\\ 
 +Adding or removing too many groups at once is not supported if using WinRM to manage groups. Lenght limitation of environment variable on Windows is 8 191 characters so if combination of all added and removed group's DNs plus comas, doublequotas and the script itself is longer than that cmd.exe just ignores it. The result is no script is being run and no error or exception ocures. It is relatively safe to add or remove about 50-100 groups at once.\\ 
 +\\ 
 +TODO: Using AD to manage groups should fix this issue - once it is properly tested, write here that when using supportASCrossDomainProvisioning, the connector can add or remove any number of groups\\ 
 +</WRAP>**
  
 IdM 11.2.0 has support for cross domain. You need connector version 1.0.7 IdM 11.2.0 has support for cross domain. You need connector version 1.0.7
Line 271: Line 293:
   * <nowiki>Config___Create</nowiki> via WinRM connector (Powershell) - true   * <nowiki>Config___Create</nowiki> via WinRM connector (Powershell) - true
  
-Scripts can be found on [[https://github.com/bcvsolutions/winrm-ad-connector/tree/develop/scripts_python3/ad|GitHub]]+TODO: fix version number when it is released 
 + 
 +Idm 14.?.? has support for cross domain via AD. You need connector 1.0.15 
 + 
 +Use the following configuration: 
 + 
 +  * <nowiki>Config___Update</nowiki> via AD connector - true 
 +  * <nowiki>Config___Create</nowiki> via AD connector - true 
 +  * **<nowiki>Additional___Use</nowiki> only WinRM for groups - false** 
 +  * **prohibitWinRMCrossDomainProvisioning - true** 
 +  * **supportADCrossDomainProvisioning - true** 
 +=== Scripts can be found on GitHub === 
 + 
 +=== Send attributes only to WinRM === 
 + 
 +In some cases, when you are using AD and WinRM for same operation, you want to use some attributes only in WinRM (powershell). 
 + 
 +The reason is that is some attribute for script and AD has no clue about this attribute and the AD part will fail. 
 + 
 +To achieve this, you can specify, which attributes should be send only to WinRM. 
 + 
 +  * Go to system detail - Configuration 
 +  * Go to tab Additional connector configuration 
 +  * Click on Manage attributes 
 +  * Add new attribute with code attributesForWinRM 
 +      * Attribute is Short text and multivalued 
 +  * Save it and go back to Additional connector configuration 
 +  * Fill attribute names which should be send only to WinRM 
 +  * Each name on it's own lane 
 +  * Names should be the ones which are in schema. 
 + 
 + 
 +====== Interesting articles about WinRM ====== 
 + 
 +  * [[https://www.bloggingforlogging.com/2018/01/24/demystifying-winrm/|https://www.bloggingforlogging.com/2018/01/24/demystifying-winrm/]]
  
  
  • by kucerar