Configuration and Security

Article
10/08/2009

Applies To: Windows Server 2003 R2

This topic discusses how to set up Windows Remote Management (WinRM) to work over HTTPS, a secure protocol that requires a certificate, and over HTTP. It also discusses how to configure a WinRM Listener, which enables communication with WinRM in various scenarios.

Configuring WinRM to Use HTTPS

Windows Remote Management (WinRM) in Windows Server 2003 R2 supports two different transports, HTTPS and HTTP.

Note

The HTTP protocol is included for troubleshooting purposes only and should not be used in production environments. While WinRM will still authenticate the communication, the data will not be encrypted and is sent as clear text on the network. If IPSec is configured between two machines, then it should be safe to use HTTP in that scenario.

For HTTPS, a secure protocol, WinRM requires a server certificate to operate properly (this certificate is used for encryption of the communication channel). The easiest way to generate these certificates is to use Microsoft Certificate Services.

Note

This certificate needs to be marked as a Server Authentication Certificate. It must also support Secure Sockets Layer (SSL). No certificate needs to be configured for the WinRM client. The certificate is used only if the WinRM service is enabled for remote access.

The table below lists some documents covering Microsoft Certificate Services:

Title	Document Link
Trigger Automatic Enrollment for Certificates	https://technet2.microsoft.com/WindowsServer/en/Library/c4e272e9-e12d-45eb-b8f2-26a549fd09e51033.mspx
Certificate Services Best practices	https://technet2.microsoft.com/WindowsServer/en/Library/b70185ed-93aa-4346-b869-9913282086af1033.mspx
Command-line utility for managing certificates: Certutil.exe	https://www.microsoft.com/resources/documentation/WindowsServ/2003/standard/proddocs/en-us/Default.asp?url=/resources/documentation/windowsserv/2003/standard/proddocs/en-us/sag_cs_certutil2.asp
Importing and Exporting Certificates	https://www.microsoft.com/resources/documentation/WindowsServ/2003/standard/proddocs/en-us/Default.asp?url=/resources/documentation/WindowsServ/2003/standard/proddocs/en-us/sag_CMimportExport.asp

Determining the Certificate Thumbprint

Once the certificate infrastructure is in place, the thumbprint or hash of the certificate to be used must be configured with the WinRM service for it to function completely. The Certificates MMC snap-in is used to determine the certificate thumbprint:

From the Start menu, click Run.
Enter mmc in the Open: field and press OK.
Choose the Add/Remove Snap-in option from the File menu.
Click the Add button.
Choose the Certificates snap-in and press the Add button:
Choose the Computer account option and press the Next button:
Ensure that the default for Local Computer is selected and press the Finish button.
Press the Close button.
Press the OK button.
Expand the Certificates (Local Computer) element (in the left pane).
Expand the Personal element (in the left pane).
Highlight the Certificates element (in the left pane):
Double-click on the desired certificate from the right pane:
Choose the Details tab in the Certificate property page.
Select the Thumbprint field.
Highlight the thumbprint value and copy it to the Clipboard by pressing Ctrl+C (you will use this value in the next section):

Configuring WinRM to Use a Certificate

Configuration of the HTTPS Certificate to be used by WinRM is done using the WinRM Command-Line tool (winrm.vbs). WinRM uses a specific uniform resource identifier (URI) to access its configuration information:

wsman:microsoft.com/wsman/2005/06/config

The current configuration can be returned using the following command:

winrm get wsman:microsoft.com/wsman/2005/06/config

The command returns the current configuration in the following form:

Config
    MaxEnvelopeSizekb = 50
    MaxTimeoutms = 60000
    MaxBatchItems = 20
    SoapTraceEnabled = false
    MaxProviderRequests = 25
    Client
        NetworkDelayms = 5000
        URLPrefix = wsman
        HTTP
            Port = 80
            Unencrypted
                Basic = false
                Digest = false
                Negotiate = false
        HTTPS
            Port = 443
            Basic = true
            Digest = true
            Negotiate = true
            Mutual = false
    Service
        RootSDDL = O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)
        MaxConcurrentOperations = 100
        EnumerationTimeoutms = 60000
        MaxClientCertInfoSize = 16384
        MaxConnections = 5
        HTTP
            Unencrypted
                Basic = false
                Negotiate = false
        HTTPS
            Basic = true
            Negotiate = true
            Mutual = false

To see the configuration in XML format, the following command can be executed:

winrm get wsman:microsoft.com/wsman/2005/06/config -format:#xml

This will return the following XML output:

<cfg:Config xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config.xsd">
  <cfg:MaxEnvelopeSizekb>50</cfg:MaxEnvelopeSizekb> 
  <cfg:MaxTimeoutms>60000</cfg:MaxTimeoutms> 
  <cfg:MaxBatchItems>20</cfg:MaxBatchItems> 
  <cfg:SoapTraceEnabled>false</cfg:SoapTraceEnabled> 
  <cfg:MaxProviderRequests>25</cfg:MaxProviderRequests> 
   <cfg:Client>
    <cfg:NetworkDelayms>5000</cfg:NetworkDelayms> 
    <cfg:URLPrefix>wsman</cfg:URLPrefix> 
    <cfg:HTTP>
      <cfg:Port>80</cfg:Port> 
          <cfg:Unencrypted>
        <cfg:Basic>false</cfg:Basic> 
        <cfg:Digest>false</cfg:Digest> 
        <cfg:Negotiate>false</cfg:Negotiate> 
      </cfg:Unencrypted>
    </cfg:HTTP>
    <cfg:HTTPS>
      <cfg:Port>443</cfg:Port> 
      <cfg:Basic>true</cfg:Basic> 
      <cfg:Digest>true</cfg:Digest> 
      <cfg:Negotiate>true</cfg:Negotiate> 
      <cfg:Mutual>false</cfg:Mutual> 
    </cfg:HTTPS>
  </cfg:Client>
   <cfg:Service>
 <cfg:RootSDDL>O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)</cfg:RootSDDL> 
    <cfg:MaxConcurrentOperations>100</cfg:MaxConcurrentOperations> 
    <cfg:EnumerationTimeoutms>60000</cfg:EnumerationTimeoutms> 
    <cfg:MaxClientCertInfoSize>16384</cfg:MaxClientCertInfoSize> 
    <cfg:MaxConnections>5</cfg:MaxConnections> 
    <cfg:HTTP>
      <cfg:Unencrypted>
        <cfg:Basic>false</cfg:Basic> 
        <cfg:Negotiate>false</cfg:Negotiate> 
      </cfg:Unencrypted>
    </cfg:HTTP>
    <cfg:HTTPS>
      <cfg:Basic>true</cfg:Basic> 
      <cfg:Negotiate>true</cfg:Negotiate> 
      <cfg:Mutual>false</cfg:Mutual> 
    </cfg:HTTPS>
  </cfg:Service>
</cfg:Config>

Creating Listener Instances

Multiple WinRM Listener instances can be created on a single system. The Listener instances are differentiated by the IP address and the port.

To configure the Listener HTTPS, a Listener instance must be created. The following command can be issued (using the thumbprint copied from the Certificates MMC snap-in in the previous section) to create an instance:

winrm create wsman:microsoft.com/wsman/2005/06/config/Listener?IP=192.168.2.1+Port=443 @{Hostname="host";CertificateThumbprint="xxx"}

Where:

•IP is the TCP/IP address of the Listener system.

•Port is the TCP/IP port that the Listener is to listen to requests on.

•Hostname is the name of the system as it appears in the Certificate.

•CertificateThumbprint is the thumbprint copied from the Certificates MMC Snap-in from the previous section. Note that you must remove the spaces from between the two-digit hex values in the thumbprint as it appears in the Certificate dialog box, for example, CertificateThumbprint="b7a24c3f42 …".

Note

In the URI, "Listener" must be capitalized. When using the Create or Invoke commands, the last part of the resource URI must match case-wise the top-level element of the expected XML.

If the configuration settings are correct, the following response is returned:

<wxf:ResourceCreated xmlns:wxf="https://schemas.xmlsoap.org/ws/2004/09/transfer"xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsman="https://schemas.xmlsoap.org/ws/2005/06/management">
<wsa:Address>https://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous?ResourceURI=(wsman:microsoft.com/wsman/2005/06/config/listener)</wsa:Address>
  <wsa:ReferenceParameters>
    <wsman:SelectorSet>
      <wsman:Selector Name="IP">192.168.2.1</wsman:Selector>
      <wsman:Selector Name="Port">443</wsman:Selector>
    </wsman:SelectorSet>
  </wsa:ReferenceParameters>
</wxf:ResourceCreated>

Note

The WinRM Command Line interface supports the configuration of Listener instances using IPv6. The IPv4 address is simply replaced by the IPv6 address.

To configure the Listener for HTTP, the following command can be issued to create an instance:

winrm create wsman:microsoft.com/wsman/2005/06/config/Listener?IP=192.168.2.1+Port=80 @{Hostname="host";Transport="http"}

Where:

IP is the TCP/IP address of the Listener system.
Port is the TCP/IP port that the Listener is to listen to requests on.
Hostname is the name of the system as it appears in the Certificate.

If the configuration settings are correct, the following response is returned:

<wxf:ResourceCreated xmlns:wxf="https://schemas.xmlsoap.org/ws/2004/09/transfer"xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsman="https://schemas.xmlsoap.org/ws/2005/06/management">
<wsa:Address>https://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous?ResourceURI=(wsman:microsoft.com/wsman/2005/06/config/listener)</wsa:Address>
  <wsa:ReferenceParameters>
    <wsman:SelectorSet>
      <wsman:Selector Name="IP">192.168.2.1</wsman:Selector>
      <wsman:Selector Name="Port">443</wsman:Selector>
    </wsman:SelectorSet>
  </wsa:ReferenceParameters>
</wxf:ResourceCreated>

Configuring a Listener Instance Using DHCP

WinRM Listener instances can be configured on systems using DHCP to get their IP addresses. To create a Listener instance on a DHCP-enabled network interface card (NIC), the MAC address of the NIC is required and the following command can be used:

winrm create wsman:microsoft.com/wsman/2005/06/config/Listener?IP=*+Port=443 @{Hostname="host";MACAddress="12-34-56-78-90-AB";CertificateThumbprint="xxx"}

This configures the WinRM service to enumerate all the IP addresses on that NIC and listen on the DHCP-assigned address of the NIC.

Note

There is a limitation of a single Listener instance for every NIC. For example, on a system with two NICs, only two Listener instances can be created.

Co-Existing with Internet Information Server

WinRM can co-exist with Internet Information Server (IIS) if it is configured for SSL communication. In this instance, WinRM checks to see if the shared certificate configuration of SSL can be reused. If it can, WS-Management will use the same certificate configuration.

Note

Deleting a shared IIS configuration from IIS may interfere with WS-Management communications. If an administrator creates a WS-Management listener that shares an HTTPS port with IIS, and later removes the SSL port configuration from IIS, this may cause the WS-Management Listener to stop responding.

Automating WinRM Configuration

To simplify automatic configuration of the WinRM service, the WinRM Configuration Plug-in supports helper methods to retrieve certificates from the machine store. These methods can be performed locally or against a remote machine and can then be used to automatically configure the certificate. Note that Listener configuration can be done only locally.

In this case, a hostname—either the NetBIOS or Fully-Qualified Domain Name (FQDN)—is specified as the input parameter. The first certificate whose CN matches the hostname and whose EKU is set to server authentication is returned.

In this example, the command retrieves configuration from host.fabrikam.com using the FQDN:

winrm invoke Retrieve wsman:Microsoft.com/wsman/2005/06/config/Certificate  @{Hostname="host.fabrikam.com"}

If successful, a typical result will be returned as shown below with the Certificate Thumbprint embedded within the XML:

<cfg:Retrieve_OUTPUT xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config/certificate.xsd">
<cfg:CertificateThumbprint>4907de1950d4a162926d56cb41392d388aac874a</cfg:CertificateThumbprint>
</cfg:Retrieve_OUTPUT>

Note

Once this Certificate Thumbprint is available, a Listener instance can be created using the steps outlined in the previous section.

If there is no certificate that matches the above criteria, an error is returned:

<f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32898" Machine="AMD64-R3-10">
  <f:Message>
    <f:ProviderFault providerId="A855B0EE-65C2-4282-830B-7FA181E73BFF">
      <f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32898" Machine="">
        <f:Message>The requested certificate was not found.</f:Message>
      </f:WSManFault>
    </f:ProviderFault>
  </f:Message>
</f:WSManFault>
Error number: -2146991998 0x80078082
The requested certificate was not found.

Another important piece of information required for the automated configuration of WinRM is whether the WinRM service is installed and running properly.

WMI can be used to check whether the WinRM service is installed. To do this, simply enumerate the Win32_Service class and look for service whose name is winrm.

In order to check whether the WinRM service is running on a machine, a Get request on a specific URI (the URI named "this") can be used. If the WinRM service is running, an XML response is returned with information about the service.

The command to perform this Get operation is:

winrm get wsman:system/2005/06/this -target:host.acme.com

The response would include the version and capabilities of the service:

<t:This xmlns:t="https://schemas.xmlsoap.org/ws/2005/06/management/this">
  <t:Vendor>Microsoft Corporation</t:Vendor>
  <t:Version>OS: 5.2.3790 SP: 1.0 Stack: 1.0</t:Version>
  <t:Access>
    <t:Compliance>https://schemas.xmlsoap.org/ws/2005/06/management</t:Compliance>
    <t:Action>https://schemas.xmlsoap.org/ws/2004/09/transfer/Get</t:Action>
    <t:Action>https://schemas.xmlsoap.org/ws/2004/09/transfer/Put</t:Action>
    <t:Action>https://schemas.xmlsoap.org/ws/2004/09/transfer/Create</t:Action>
    <t:Action>https://schemas.xmlsoap.org/ws/2004/09/transfer/Delete</t:Action>
    <t:Action>https://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate</t:Action>
  </t:Access>
  <t:Transports>
    <t:Transport Name="https://www.ietf.org/rfc/rfc2818.txt">
      <t:Auth>wsman:auth/basic</t:Auth>
      <t:Auth>wsman:auth/https-mutual</t:Auth>
    </t:Transport>
  </t:Transports>
</t:This>

If the WinRM service is not running the following error is returned:

Specified destination cannot be connected to.

Viewing Listener Instances

To view all the Listener instances that exist on the system, the following command can be executed:

winrm enumerate wsman:microsoft.com/wsman/2005/06/config/Listener

This returns a result similar to this:

<wsman:Results xmlns:wsman="https://schemas.microsoft.com/ws/2005/03/wsman/results">
  <cfg:Listener xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config/listener.xsd">
    <cfg:IP>192.168.2.1</cfg:IP>
    <cfg:Port>443</cfg:Port>
    <cfg:Hostname>host.acme.com</cfg:Hostname>
    <cfg:MACAddress/>
    <cfg:Enabled>true</cfg:Enabled>
    <cfg:URLPrefix>wsman</cfg:URLPrefix>
    <cfg:Transport>HTTPS</cfg:Transport>
    <cfg:CertificateThumbprint>49 07 de 19 50 d4 a1 62 92 6d 56 cb 41 39 2d 38 8a ac 87 4a</cfg:CertificateThumbprint>
  </cfg:Listener>
</wsman:Results>

If multiple Listener instances are created, the resulting output XML is similar to this:

<wsman:Results xmlns:wsman="https://schemas.microsoft.com/ws/2005/03/wsman/results">
  <cfg:Listener xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config/listener.xsd">
    <cfg:IP>192.168.2.1</cfg:IP>
    <cfg:Port>443</cfg:Port>
    <cfg:Hostname>host.acme.com</cfg:Hostname>
    <cfg:MACAddress/>
    <cfg:Enabled>true</cfg:Enabled>
    <cfg:URLPrefix>wsman</cfg:URLPrefix>
    <cfg:Transport>HTTPS</cfg:Transport>
    <cfg:CertificateThumbprint>49 07 de 19 50 d4 a1 62 92 6d 56 cb 41 39 2d 38 8a ac 87 4a</cfg:CertificateThumbprint>
  </cfg:Listener>
  <cfg:Listener xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config/listener.xsd">
    <cfg:IP>192.168.2.1</cfg:IP>
    <cfg:Port>444</cfg:Port>
    <cfg:Hostname>host.acme.com</cfg:Hostname>
    <cfg:MACAddress/>
    <cfg:Enabled>true</cfg:Enabled>
    <cfg:URLPrefix>wsman</cfg:URLPrefix>
    <cfg:Transport>HTTPS</cfg:Transport>
    <cfg:CertificateThumbprint>49 07 de 19 50 d4 a1 62 92 6d 56 cb 41 39 2d 38 8a ac 87 4a</cfg:CertificateThumbprint>
  </cfg:Listener>
</wsman:Results>

If the configuration information is incorrect, Fault XML will be returned followed by the message "The supplied SOAP violates the corresponding XML schema definition."

Modifying an Existing Listener Instance

To modify the configuration of an existing Listener instance, use the Put action. For example, to disable a Listener instance, execute the following command:

winrm put wsman:microsoft.com/wsman/2005/06/config/Listener?IP=192.168.2.1+Port=443 @{Enabled="False"}

A successful modification of the Listener instance returns the current configuration:

<cfg:Listener xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config/listener.xsd">
  <cfg:IP>192.168.2.1</cfg:IP>
  <cfg:Port>443</cfg:Port>
  <cfg:Hostname>amd64-r3-10.wmx.microsoft.com</cfg:Hostname>
  <cfg:MACAddress/>
  <cfg:Enabled>false</cfg:Enabled>
  <cfg:URLPrefix>wsman</cfg:URLPrefix>
  <cfg:Transport>HTTPS</cfg:Transport>
  <cfg:CertificateThumbprint>49 07 de 19 50 d4 a1 62 92 6d 56 cb 41 39 2d 38 8a ac 87 4a</cfg:CertificateThumbprint>
</cfg:Listener>

An incorrect modification of the Listener instance results in Fault XML being returned:

<f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32833" Machine="AMD64-R3-10">
  <f:Message>
    <f:ProviderFault providerId="A855B0EE-65C2-4282-830B-7FA181E73BFF">
      <f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32833" Machine="">
        <f:Message>Input xml contained an unrecognized xml element "enabled".  Double check the spelling and case of the element name.</f:Message>
      </f:WSManFault>
    </f:ProviderFault>
  </f:Message>
</f:WSManFault>

Error number: -2146992063 0x80078041
The supplied SOAP violates the corresponding XML schema definition.

Note

The URIs listed here are case sensitive. For example, Listener and Enabled must have their first letters capitalized.

Deleting a Listener Instance

To delete a Listener instance that exists on the system, execute the following command:

winrm delete wsman:microsoft.com/wsman/2005/06/config/Listener?IP=192.168.2.1+Port=444

If the instance is deleted successfully, no response is returned. If an attempt is made to delete an instance that does not exist, the following fault XML is returned:

<f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32768" Machine="AMD64-R3-10">
  <f:Message>
    <f:ProviderFault providerId="A855B0EE-65C2-4282-830B-7FA181E73BFF">
      <f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32768" Machine="">
        <f:Message>The resource identified by the resource uri and selectors could not be found.</f:Message>
      </f:WSManFault>
    </f:ProviderFault>
  </f:Message>
</f:WSManFault>
Error number: -2146992128 0x80078000
The resource identified by the resource uri and selectors could not be found.

Configuration and Security

Configuring WinRM to Use HTTPS

Determining the Certificate Thumbprint

Configuring WinRM to Use a Certificate

Creating Listener Instances

Configuring a Listener Instance Using DHCP

Co-Existing with Internet Information Server

Automating WinRM Configuration

Viewing Listener Instances

Modifying an Existing Listener Instance

Deleting a Listener Instance

Additional resources