Skip to end of metadata
Go to start of metadata

Introduction

The AD/LDAP connector has ability to execute remote commands and PowerShell scripts on Windows machines using the Windows remote management interfaces (WinRM/WS-Man).

This feature is only available in AD/LDAP connector version 1.4.2.18 and later.

Configuration

The WinRM access needs additional configuration:

Executing the Scripts

This ability is implemented as usual connector scripting capability. Therefore it is possible to use provisioning scripts before and after any provisioning operations:

Supported languages

There are currently two "languages" supported by the connector scripting capability:

 

Language nameInterpreted byDescription
cmdcmd.exeExecuting simple Windows commands.
powershellPowerShellPowerShell commands, each executed separately in its own PowerShell instance. This requires additional overhead to execute powershell.
powerhellPowerShellPowerShell commans executed in one PowerShell instance. This forms a quasi-session. The PowerShell interpreter is executed and initialized only once. Then the commands are sent to the PowerShell one by one.
WARNING: All the commands share the same PowerShell, so they can influence each other (e.g. they are using the same variables). Be careful.
exchangePowerShell (Exchange)PowerShell commans executed in one PowerShell instance which has been initialized with Exchange snap-ins.
WARNING: All the commands share the same PowerShell, so they can influence each other (e.g. they are using the same variables). Be careful.

Script arguments

Passing arguments to the script can have two different formats. Which of the formats is used is based upon AD resource attribute powershellArgumentStyle.

powershellArgumentStyle
FormatDescription
dashed (default)command -arg1 val1 -arg2 val2

The arguments are encoded in the commands in a windows-like dashed form.

Final command example: "jump.bat -height 100 -distance 200"

variables$arg1 = 'val1'; command

This option is convenient for more complex commands, where arguments are used inline.

Connector sets arguments as powershell variables, that can be then read with $ notation.

Example: see bellow

Please note that command represents <code></code> part of the script.

Example how powershell command with arguments may be invoked in midPoint:

powershellArgumentStyle=variables

Windows Server Setup

Remote powershell is executed using WinRM service which is using the WS-Management standard web services. The server side is controlled with winrm tool.

Using HTTP and basic authentication:

Using CredSSP:

Enabling HTTPS:

Do not forget to add firewall rule to allow connection to the port.

For a user to be able to use WinRM, the user must be member of Remote Management Users group.

Computer Management > Services and Applications > WMI Control > Security (select Root) > Security: add the Remote Management Users group, allow Execute Methods and Remote Enable permission. Click Advanced button and change the application of the permission to "This namespace and subnamespaces". For more details see here: https://www.sevecek.com/Lists/Posts/Post.aspx?ID=280

This works in some cases but it does not for other. If it does not work then there is another way. Use the command:

And set read and execute rights for the Remote Management Users group.

To enable access to the WinRM service in a subdomain use the following command on the target computer:

List winrm configuration and listeners form elevated command prompt:

 

Microsoft Exchange

This method is recommended for midPoint 3.6 and later (connector version 1.4.4 and later)

Connector is capable of provisioning mailboxes to Microsoft Exchange mail server via invoking powershell interface of the Exchange server. The connector provides a special exchange scripting language, which is in a fact a PowerShell initialized with Exchange snap-ins.

Microsoft Exchange (deprecated method)

This method is recommended for midPoint 3.5 and earlier (connector versions before 1.4.4)

Connector is capable of provisioning mailboxes to Microsoft Exchange mail server via invoking powershell interface of the Exchange server.

  • Make sure winrm is enabled as described in above section or consult Troubleshooting.
  • User specified in winRmUsername needs to have sufficient Exchange access rights - e.g. "Organization Management" AD group assigned.
  • CredSSP Authentication is required to authorize user to Exchange commands:
    • On Exchange server run: powershell -command Enable-WSManCredSSP Server
    • On winRmHost (Exchange server or other domain computer): powershell -command Enable-WSManCredSSP Client -DelegateComputer <exchange_server_hostname>


Exchange Powershell

We recommend pointing the winRmHost property to Exchange server hostname rather than to AD controller server. Host server needs to have special Exchange powershell installed, which consumes quite a lot of resources.

 

AD/LDAP connector 1.4.4 or later supports CredSSP protocol. In that case the use of CredSSP is easy, it just need setting for authentication mechanism and domain:


TODO: complete sample

Prerequisites

The are few things that you need to setup/check first. In case your winRmHost points to other computer in the domain than Exchange server, you need to set this computer as well.

  • Make sure winrm is enabled as described in above section or consult Troubleshooting.
  • User specified in winRmUsername needs to have sufficient Exchange access rights - e.g. "Organization Management" AD group assigned.
  • CredSSP Authentication is required to authorize user to Exchange commands:
    • On Exchange server run: powershell -command Enable-WSManCredSSP Server
    • On winRmHost (Exchange server or other domain computer): powershell -command Enable-WSManCredSSP Client -DelegateComputer <exchange_server_hostname>

Exchange Powershell

We recommend pointing the winRmHost property to Exchange server hostname rather than to AD controller server. Host server needs to have special Exchange powershell installed, which consumes quite a lot of resources.

Creating resource from sample

Sample resource XML can be found here.

Sample resource is set to invoke enable-mailbox command in Exchange powershell after new AD user has been created.

For connectors prior to version 1.4.4 the integration is not straightforward due to the lack of CredSSP  in the connector. Various workarounds have to be used. Basically winrs is launched on the remote machine to connect locally with -a[llow]d[elegate].

After sample resource is imported into midPoint, please set your actual hostnames and passwords, save the resource and click "Refresh schema" button. There are some Exchange attributes preset in the sample, however if you need more, you have to set them as operational and add to schema manually. Connector does not see all Exchange attributes - 

JIRA Issues Macro: Data cannot be retrieved due to an unexpected error

Troubleshooting

General TIP

If you encounter any WinRM problem where you are not sure if your remote WinRM interface is configured correctly or reachable via network. I suggest using winrs command from (preferably different) Windows machine. Following simple command executes "hostname" command on remote machine via WinRM HTTPs:

Using elevated cmd.exe is recommended.

java.io.IOException: Authorization loop detected on Conduit

This usually means user authentication to WinRM failed. Check that your user and password are correct and that you are connecting to enabled interface - e.g. when using basic HTTP, make sure winrm/config is set properly (see above).

Script action takes long time to finish

Well.. this can mean any general problem. Try running winrs tool to simulate problem right in the Windows first. There are few tips:

  • When using HTTPs, make sure your environment (Java, Tomcat) trusts certificate that is used on remote machine.
  • Also make sure that HTTPs port (e.g. 5986) is enabled on the Windows Firewall for inbound connections (by default it is NOT).
  • When using HTTPs make sure your resource "AD host" is specified via hostname (matching certificate CN) rather than IP.

Exchange - The term 'enable-mailbox' is not recognized as the name of a cmdlet

Make sure that winRmHost points to Windows server that has special Exchange power shell installed.

Exchange - ADInvalidCredentialException

Apart from obvious meaning (bad username/password) this could also mean that CredSSP Authentication (winrs -ad) is not used. If you are not sure whether this is the case, try running some simple command like "hostname" instead of Exchange command. If this is the case, check Prerequisites chapter on how to allow CredSSP on both client and server.

See Also

  • No labels