Windows Remote Management (WinRM) Service#

Configure WinRM#

This procedure configures the Windows Remote Management (WinRM) service with the appropriate settings for VOSS Automate.

Note

VOSS Automate uses the Web Services-Management protocol (WSMan) to create the PowerShell sessions that manage Microsoft UC applications.

On Windows computers, the Windows Remote Management (WinRM) service implements WSMan. You will need to configure WinRM on a PowerShell Proxy running on Windows Server 2019.

  1. Open an elevated PowerShell session.

  2. Issue the following commands:

    Enable-WSManCredSSP -Role Server -Force
Enable-WSManCredSSP -Role Client -DelegateComputer \* -Force
Set-Item WSMan:\localhost\Service\AllowUnencrypted $true
Set-Item WSMan:\localhost\Service\Auth\Basic $true
Set-Item WSMan:\localhost\Client\AllowUnencrypted $true
Set-Item WSMan:\localhost\Client\Auth\Basic $true
Set-Item WSMan:\localhost\Client\TrustedHosts '<server identity>'
Set-Item -path WSMan:\localhost\Shell\IdleTimeout -Value '1800000'

    Note

    • When setting the TrustedHosts value, you’ll need to provide the identity of the server on which you’re executing these commands:

      • If this is a standalone PowerShell Proxy (not behind a load balancer), provide the server’s IP address and FQDN, with a comma between them.

      • If this PowerShell Proxy is behind a load balancer, append the FQDN of the load balancer’s virtual interface.

      For example, assume the server’s FQDN is psproxy01.domain.com and its IP address is 10.1.1.10. If the server is not behind a load balancer, the value for TrustedHosts (including the quotes) will be:

      '10.1.1.10,psproxy01.domain.com'

      If the server is behind a load balancer, and the FQDN of the load balancer’s virtual interface is psproxy.domain.com, then provide the following value for TrustedHosts, including the quotes:

      '10.1.1.10,psproxy01.domain.com,psproxy.domain.com'

    • The IdleTimeout setting is configured for 1800000ms (30mins) to optimize the reuse of sessions on PowerShell to avoid stuck sessions. If this occurs you may see periodic errors in your transactions with the failure message similar to below:

      API Call Error [400] [N/A] [Trying to connect to session:[PSSession]

WinRM over HTTPS#

From release 21.4-PB1, an option is available to use secure WinRm transport, allowing VOSS Automate and MS Proxy to communicate over HTTPS.

These steps describe the initial setup to use this option:

  1. From an elevated PowerShell prompt:

    New-SelfSignedCertificate -DnsName "<Proxy_FQDN>" -CertStoreLocation Cert:\LocalMachine\My

    Example output:

    PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My

Thumbprint Subject
---------- -------
4A90ABCD61ACB1D5260D310EC68BC154822619DE CN=<Proxy_FQDN>

    Capture the thumbprint of the generated certificate.

  2. From an elevated PowerShell prompt:

    winrm create winrm/config/Listener?Address=*+Transport=HTTPS '@{Hostname="<Proxy_FQDN>"; CertificateThumbprint="<Captured_thumbprint>"}'

    Example output:

    ResourceCreated
Address = http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
ReferenceParameters
ResourceURI = http://schemas.microsoft.com/wbem/wsman/1/config/listener
SelectorSet
Selector: Address = *, Transport = HTTPS

  3. Add an inbound firewall rule in Windows Firewall with Advanced Security:

    Note

    Any firewalls between VOSS Automate and the PowerShell Proxy, including Windows Firewall on the proxy, must permit the following connections (WinRM Firewall Settings):

    Service

    Protocol

    Port

    WinRM 2.0 (HTTP)

    TCP

    5985

    WinRM 2.0 (HTTPS)

    TCP

    5986 (recommended)

    It is strongly recommended that you use port 5986 (HTTPS), and disable port 5985 (HTTP).

    • General / Name: WinRM HTTPS

    • General / Enabled: checked

    • General / Action: Allow the connection

    • Protocols and Ports / Protocol type: TCP

    • Protocols and Ports / Local port: 5986

    • Advanced / Profiles: checked domain, private, and public. (In practice you would probably want to restrict this.)

    WinRM HTTPS Properties would then show:

    ../../_images/winrm-https-properties.png

    Note

    Upon upgrade to release 21.4-PB1 all transport configurations will default to HTTPS. For existing PowerShell configurations with transport over HTTP, the driver parameter winrm_transport can be set to plaintext and can be manually added to the data/MSTeamsOnline instance to ensure backward compatibility temporarily. If integrating with Exchange Online then the same driver parameter can be added to data/MSExchangeOnline temporarily.

    Contact VOSS support to assist in the reconfiguration of your winrm driver.