To establish a connection between the PowerShell plug-in and Windows PowerShell, you must configure WinRM to use one of the supported communication protocols.

The PowerShell plug-in supports Windows Remote Management (WinRM) 2.0 as a management protocol.

The following authentication methods are supported.
Authentication method Details
Basic Non-secure authentication mechanism that requires a user name and a password.
Kerberos Secure authentication protocol that uses tickets to verify the identity of the client and the server.
Note: The PowerShell plug-in does not support delegation of user credentials in WinRM and CredSSP is not a supported authentication method.

WinRM Through HTTP

The PowerShell plug-in supports communication with the WinRM host through the HTTP protocol. Although WinRM authenticates the communication, the data transfer is not encrypted and is sent as plain text on the network. You should use the HTTP protocol if IPSec is configured between the machines that communicate.

To use Basic authentication, you must set the AllowUnencrypted property to true in both the service and client WinRM configuration. For an example of HTTP configuration, see Configure WinRM to Use HTTP.

WinRM Through HTTPS

The PowerShell plug-in supports communication with the WinRM host through the HTTPS protocol. You can use the HTTPS protocol as a more secure communication method.

To use the HTTPS protocol, you must generate a certificate for server authentication and install the certificate on the WinRM host. For an example of HTTPS configuration, see Configure WinRM to use HTTPS.

Kerberos authentication

You can use Kerberos authentication when you add and manage a PowerShell host. With Kerberos authentication, domain users can run commands on remote PowerShell-enabled machines over WinRM.

To configure WinRM on the PowerShell host, run the following command. 
winrm quickconfig
winrm set winrm/config/service/auth '@{Kerberos="true"}'
winrm set winrm/config/winrs @{MaxMemoryPerShellMB="2048"}

For more information, see Configure Kerberos authentication for Automation Orchestrator plug-ins.

Configure WinRM to Use HTTP

You can configure the WinRM host to enable communication with the PowerShell plug-in through the HTTP protocol.

You must modify the WinRM configuration by running commands on the WinRM host machine. You can use the same machine as both the WinRM service and WinRM client.

Important: If you skip any of the steps when configuring WinRM to use HTTP, the host might not be added, and you might get an error message in the logs such as: 
Caused by: org.dom4j.DocumentException: Error on line -1 of document : Premature end of file. 
Nested exception: Premature end of file.
at org.dom4j.io.SAXReader.read(SAXReader.java:482)
at org.dom4j.DocumentHelper.parseText(DocumentHelper.java:278)
at com.xebialabs.overthere.cifs.winrm.connector.JdkHttpConnector.sendMessage(JdkHttpConnector.java:117)

Procedure

  1. Run the following command to set the default WinRM configuration values.
    c:\> winrm quickconfig
  2. (Optional) Run the following command to check whether a listener is running, and verify the default ports.
    c:\> winrm e winrm/config/listener

    The default ports are 5985 for HTTP, and 5986 for HTTPS.

  3. Enable basic authentication on the WinRM service.
    1. Run the following command to check whether basic authentication is allowed.
      c:\> winrm get winrm/config/service
    2. Run the following command to enable basic authentication.
      c:\> winrm set winrm/config/service/auth '@{Basic="true"}'
  4. Run the following command to allow transfer of unencrypted data on the WinRM service.
    c:\> winrm set winrm/config/service @{AllowUnencrypted="true"}
  5. If the channel binding token hardening level of the WinRM service is set to strict, change its value to relaxed.
    c:\> winrm set winrm/config/service/auth @{CbtHardeningLevel="relaxed"}
  6. Enable basic authentication on the WinRM client.
    1. Run the following command to check whether basic authentication is allowed.
      c:\> winrm get winrm/config/client
    2. Run the following command to enable basic authentication.
      c:\> winrm set winrm/config/client/auth @{Basic="true"}
  7. Run the following command to allow transfer of unencrypted data on the WinRM client.
    c:\> winrm set winrm/config/client @{AllowUnencrypted="true"}
  8. If the WinRM host machine is in an external domain, run the following command to specify the trusted hosts.
    c:\> winrm set winrm/config/client @{TrustedHosts="host1, host2, host3"}
  9. Run the following command to test the connection to the WinRM service.
    c:\> winrm identify -r:http://winrm_server:5985 -auth:basic -u:user_name -p:password -encoding:utf-8

Configure WinRM to use HTTPS

You can configure the WinRM host to enable communication with the PowerShell plug-in through the HTTPS protocol.

The WinRM host requires a certificate so that it can communicate through the HTTPS protocol. You can either obtain a certificate or generate one.

Prerequisites

  • Configure WinRM to use the HTTP protocol. For more information, see Configure WinRM to Use HTTP.
  • Verify that you can access the Microsoft Management Console (mmc.exe) on the WinRM host.

Procedure

  1. Generate a self-signed certificate.
    The following command line contains example syntax for creating a certificate on the WinRM host by using the Powershell Cmdlet New-SelfSignedCertificate. 
    New-SelfSignedCertificate -CertStoreLocation cert:\localmachine\my -DnsName ("machinename.subdomain.company.com", "machinename") -NotAfter (get-date).AddYears(5) -Provider "Microsoft RSA SChannel Cryptographic Provider" -KeyLength 2048

    In this example, the -NotAfter parameter specifies that the certificate will expire in 5 years. If this parameter isn't specified, the certificate expires in 1 year. Learn more about creating self-signed certificates.

  2. Add the generated certificate by using the Microsoft Management Console.
    1. Run mmc.exe.
    2. Select File > Add/Remove Snap-in.
    3. From the list of available snap-ins, select Certificates and click Add.
    4. Select Computer account and click Next.
    5. Click Finish.
    6. Verify that the certificate is installed in Console Root > Certificates (Local Computer) > Personal > Certificates and Console Root > Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
      If the certificate is not installed in the Trusted Root Certification Authorities and Personal folders, you must install it manually.
  3. Create an HTTPS listener by using the correct thumbprint and host name.
    The following command line contains example syntax for creating an HTTPS listener.

    winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="host_name";CertificateThumbprint="certificate_thumbprint"}

    Note: Omit the spaces in the certificate thumbprint.

    When the certificate expires, the listener must be deleted and created again with the new valid certificate.

  4. Test the connection.
    The following command line contains example syntax for testing the connection.

    winrs -r:https://host_name:port_number -u:user_name -p:password hostname