Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
devel:documentation:adm:systems:winrm_ad_connector [2021/09/02 12:50] kucerar |
devel:documentation:adm:systems:winrm_ad_connector [2023/11/07 15:00] urbanl [Installation] |
||
---|---|---|---|
Line 1: | Line 1: | ||
====== WinRM + AD Connector ====== | ====== WinRM + AD Connector ====== | ||
+ | |||
This connector is combining WinRM and [[https:// | This connector is combining WinRM and [[https:// | ||
Line 5: | Line 6: | ||
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). Owner of home directory can be set only locally. | * 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 | ||
* Management of OpenLims via special client which is on the windows servers and is executed from powershelll | * Management of OpenLims via special client which is on the windows servers and is executed from powershelll | ||
- | * Basically you use this to connect to system which can be controlled via powershell and is dependent on AD. | + | * Basically you use this to connect to system which can be controlled via powershell and is dependent on AD. |
- | Schema: | + | Schema: {{ ..:..: |
- | {{ :devel: | + | |
- | 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 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. | 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. | + | 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. |
- | 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 ====== | ====== 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. | This part is only what is supported by WinRM connector. AD connector has the same functionality as if you use the standalone version. | ||
Line 29: | Line 30: | ||
We implemented some features which were missing. | We implemented some features which were missing. | ||
+ | |||
* It contains more configuration fields for connecting to WinRM, which is the main purpose of this connector. | * It contains more configuration fields for connecting to WinRM, which is the main purpose of this connector. | ||
- | * Password for WinRM user is GuardedString in connector but we send is as plain text in to bash script. (This behavior is same in CMD connector for %%__PASSWORD__%% attribute) | + | * Password for WinRM user is GuardedString in connector but we send is as plain text in to bash script. (This behavior is same in CMD connector for < |
* If script return exit code other then 0 exceptions is thrown. | * If script return exit code other then 0 exceptions is thrown. | ||
* Item In folder scripts/ | * Item In folder scripts/ | ||
- | | + | |
- | * Update | + | * Update |
- | * Delete | + | * Delete |
- | * Test | + | * Test |
- | * Search | + | * Search |
- | Where " | + | Where " |
- | 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 " | Powershell scripts are in subfolders. It's not only " | ||
- | 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: | + | 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 [[..:..: |
- | Then in folder " | + | Then in folder " |
- | 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'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 ''/ |
- | It supports HTTP and HTTPS communication. HTTPS communication can be a little bit tricky to configure. You need the right | + | 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** |
- | 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, | p = winrm.protocol.Protocol(endpoint=endpoint, | ||
transport=authentication, | transport=authentication, | ||
Line 63: | Line 61: | ||
password=password, | password=password, | ||
ca_trust_path='/ | ca_trust_path='/ | ||
+ | |||
</ | </ | ||
- | **WinRM >= 1.0.5** there is configuration field called | + | |
- | 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. | + | **WinRM >= 1.0.5** |
+ | |||
===== Schema generation ===== | ===== Schema generation ===== | ||
+ | |||
Connector is supporting basic schema generation. You will get these attributes: | Connector is supporting basic schema generation. You will get these attributes: | ||
- | | + | |
- | * %%__UID__%% | + | |
- | * %%__PASSWORD__%% | + | * < |
+ | * < | ||
You need to create other attributes manually based on the system which you want to connect and you needs. | You need to create other attributes manually based on the system which you want to connect and you needs. | ||
Line 81: | Line 85: | ||
* Correctly set up network access and firewall rules to allow WinRM communication from IdM server to desired server | * Correctly set up network access and firewall rules to allow WinRM communication from IdM server to desired server | ||
* Allowed WinRM ports - 5985 for HTTP and 5986 for HTTPS (by default) | * Allowed WinRM ports - 5985 for HTTP and 5986 for HTTPS (by default) | ||
- | * 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 ConnId API to PowerShell script (examples in GIT repository https:// | + | * Write Python scripts that transform data from ConnId API to PowerShell script (examples in GIT repository |
====== Version and compatibility ====== | ====== Version and compatibility ====== | ||
+ | |||
* 1.0.0 - IdM 9.x and above | * 1.0.0 - IdM 9.x and above | ||
* 1.0.1 - IdM 9.x and above | * 1.0.1 - IdM 9.x and above | ||
* 1.0.2 - IdM 9.x and above | * 1.0.2 - IdM 9.x and above | ||
+ | |||
Cross domain feature available: | Cross domain feature available: | ||
+ | |||
* 1.0.3 - IdM LTS 9.7.x with Extras module 1.8.1 | * 1.0.3 - IdM LTS 9.7.x with Extras module 1.8.1 | ||
* 1.0.4 - IdM 10.3.0 and above | * 1.0.4 - IdM 10.3.0 and above | ||
* 1.0.5 - IdM 10.3.0 and above | * 1.0.5 - IdM 10.3.0 and above | ||
- | * 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 | ||
Line 109: | Line 116: | ||
===== Supported operations ===== | ===== Supported operations ===== | ||
- | ^ Object | + | ^Object |
- | | %%__ACCOUNT__%% | CREATE, UPDATE, DELETE, SEARCH | + | |< |
- | | %%__GROUP__%% | + | |< |
===== Managing users groups ===== | ===== 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 " | + | |
+ | When you use this connector for some system where you need to manage groups for users (OpenLims). Attribute for roles must be called " | ||
===== Scripts ===== | ===== Scripts ===== | ||
- | For more information about how to write scripts, follow [[devel:documentation: | + | For more information about how to write scripts, follow [[..:..: |
==== python ==== | ==== python ==== | ||
+ | |||
Python scripts should start with these two lines: | Python scripts should start with these two lines: | ||
- | < | + | < |
- | # -*- coding: utf-8 -*-</ | + | |
+ | # | ||
+ | # -*- 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. | ||
- | 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 | import codecs | ||
Line 132: | Line 145: | ||
command = f.read() | command = f.read() | ||
command = command.replace(" | command = command.replace(" | ||
+ | |||
</ | </ | ||
+ | |||
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 | 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. | 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> | + | <note important> |
- | < | + | |
+ | < | ||
+ | sys.stdout.reconfigure(encoding=' | ||
+ | |||
+ | </code> | ||
+ | |||
+ | <note tip> | ||
- | <note tip> | ||
- | <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' | ||
===== 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. | ||
- | | + | |
+ | | ||
* 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:// | + | * Install pywinrm and dependencies. You can follow official guide [[https:// |
- | <note tip> | + | <note tip> |
< | < | ||
+ | |||
su - connector-server | su - connector-server | ||
pip install --user pywinrm | pip install --user pywinrm | ||
#those only if you need them | #those only if you need them | ||
- | pip install --user pywinrm[kerberos] | + | pip install --user pywinrm[kerberos] |
pip install --user pywinrm[credssp] | 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. | 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. | ||
- | - Follow [[devel: | + | - Follow [[.: |
- | - Put '' | + | - Put '' |
- Put WinRM server' | - Put WinRM server' | ||
- | - Put CA certificate to AD servers in the [[devel: | + | - Put CA certificate to AD servers in the [[.: |
- | - Configure WinRM on windows server or check if WinRM is accessible. You can follow steps from our [[tutorial: | + | - Configure WinRM on windows server or check if WinRM is accessible. You can follow steps from our [[:tutorial: |
===== Configuration ===== | ===== Configuration ===== | ||
- | In configuration you have the option to configure AD connector and WinRM connector. | + | |
- | So follow WinRM configuration below and [[tutorial: | + | In configuration you have the option to configure AD connector and WinRM connector. So follow WinRM configuration below and [[:tutorial: |
Connector has few settings which need to be configured before you used it. | Connector has few settings which need to be configured before you used it. | ||
Line 177: | Line 201: | ||
=== Create script === | === Create script === | ||
+ | |||
Path to Python create script | Path to Python create script | ||
=== Powershell create script === | === Powershell create script === | ||
+ | |||
Path to powershell create script which will be loaded into python and executed on Windows | Path to powershell create script which will be loaded into python and executed on Windows | ||
=== Update script === | === Update script === | ||
+ | |||
Path to Python update script | Path to Python update script | ||
=== Powershell update script === | === Powershell update script === | ||
+ | |||
Path to powershell update script which will be loaded into python and executed on Windows | Path to powershell update script which will be loaded into python and executed on Windows | ||
=== Search script === | === Search script === | ||
+ | |||
Path to Python search script | Path to Python search script | ||
=== Powershell search script === | === Powershell search script === | ||
+ | |||
Path to powershell search script which will be loaded into python and executed on Windows | Path to powershell search script which will be loaded into python and executed on Windows | ||
=== Delete script === | === Delete script === | ||
+ | |||
Path to Python delete script | Path to Python delete script | ||
=== Powershell delete script === | === Powershell delete script === | ||
+ | |||
Path to powershell delete script which will be loaded into python and executed on Windows | Path to powershell delete script which will be loaded into python and executed on Windows | ||
=== Test script === | === Test script === | ||
+ | |||
Path to Python test script | Path to Python test script | ||
=== Endpoint === | === Endpoint === | ||
- | URL to the endpoint, where is WinRM accessible. Usually https:// | + | |
+ | URL to the endpoint, where is WinRM accessible. Usually | ||
=== Authentication schema === | === Authentication schema === | ||
+ | |||
One from supported values - basic, ntlm, kerberos, credssp | One from supported values - basic, ntlm, kerberos, credssp | ||
=== User === | === User === | ||
+ | |||
Username for user which will be used for authentication to WinRM | Username for user which will be used for authentication to WinRM | ||
=== Password === | === Password === | ||
+ | |||
Password for this user | Password for this user | ||
=== CA trust path === | === CA trust path === | ||
+ | |||
Path to certificate which will be used in HTTPS communication. E.g / | Path to certificate which will be used in HTTPS communication. E.g / | ||
=== Ignore CA validation === | === Ignore CA validation === | ||
+ | |||
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! | ||
- | + | ||
- | | + | 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. {{ ..:..: |
- | 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. | + | |
- | {{ :devel: | + | |
- | You can configure the order of connectors. Default behavior is that AD connector is first. | + | |
- | {{ :devel: | + | |
- | < | + | |
=== Cross domain configuration === | === Cross domain configuration === | ||
+ | |||
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 | ||
Do the following configuration in IdM: | Do the following configuration in IdM: | ||
- | | + | |
- | * %%Config___Update%% via WinRM connector (Powershell) - true | + | |
- | * %%Config___Create%% via WinRM connector (Powershell) - true | + | * < |
+ | * < | ||
Scripts can be found on [[https:// | Scripts can be found on [[https:// | ||
- | On tab "Additional connector configuration" fill folowinf | + | === Send attributes only to WinRM === |
- | * searchUserContainer | + | |
- | * deleteUserContainer | + | In some cases, when you are using AD and WinRM for same operation, you want to use some attributes only in WinRM (powershell). |
- | * newUserContainer | + | |
- | * domainContainer - It' | + | 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 | ||
+ | * 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' | ||
+ | * Names should be the ones which are in schema. | ||