Edit

IIS Host Plug-in Configuration

  • Article

The Windows Remote Management (WinRM) Internet Information Services (IIS) host plug-in configuration provides a hosting mechanism that allows third-party WinRM plug-ins to expose management data within the WinRM infrastructure.

The following sections describe IIS host plug-in configuration:

IIS Hosting Details

An application that configures and initializes the WinRM SOAP processor in IIS will receive requests directly from a WinRM client on another computer using the WS-Management protocol. The application must also configure an HTTP endpoint that identifies the application to ensure that all requests get routed directly to the application-specific plug-ins. The application must also configure which plug-ins to load in to the IIS host and the authorization and authentication mechanisms that are needed. When using the WinRM service within IIS, the following factors should be considered:

  • IIS does not support Kerberos authentication by default. However, an IIS module can be created to support Kerberos authentication.
  • The IIS service will not accept encrypted WinRM service requests over HTTP.
  • After you set up an IIS endpoint, the first request you send with implicit credentials will fail; however, all subsequent requests will succeed. This is a known issue with an IIS site configured with the default kernel mode authentication. If this is a blocking issue, it is recommended that you turn off kernel mode authentication.

IIS Host Configuration Model

All applications that host a WinRM Simple Object Access Protocol (SOAP) processor in IIS require configuration before they will function.

Each application configuration is separate from that of other applications. The following sets of configurations are necessary, although possibly not all the configurations need to be changed, and they are done through the main WinRM service:

  • General application configuration, including operation time-outs.
  • An authorization plug-in for authorizing LiveID requests or mapping the Windows user account to a more generic service account.
  • Operation plug-ins to be hosted and used by the WinRM SOAP processor to carry out the actual requests.

The following configurations might need to be configured within IIS:

  • Listener endpoint information defining what ports and addresses are listening for requests along with any Secure Sockets Layer (SSL) certificates.
  • Client certificate mapping to map client certificates to user accounts.
  • Authorization configuration to limit who has access to the virtual site.

The WinRM service registers port 5985 with the "wsman" prefix by default. If the compatibility HTTP listener is enabled, the WinRM Service registers port 80 with the "wsman" prefix by default. Because IIS also listens on port 80 by default, it is recommended that IIS host services create listeners on a different port.

If both the IIS and the WinRM service share port 80, the following configuration is needed to share the port:

  • The IIS host service needs to enable WinRM on an application under the site.
  • The application name needs to be added to the URI. For example: https://servername/myapplication.

Each IIS host application is stored in the IIS configuration as a web.config file residing in the physical directory corresponding to the configured virtual directory. The following section describes how the IIS configuration system works and how it can be extended to support WinRM IIS host configuration.

How IIS Configuration Works

The IIS configuration infrastructure consists of a set of XML files used to store configuration data and a set of schema files used to validate data written to or read through IIS administration APIs. At the root level, there is an ApplicationHost.config file in the same directory as IIS (typically, %windir%\System32\InetSrv\Config). This is the main configuration file for IIS, where the list of sites, applications, virtual directories, general settings, logging, caching, and so on are stored. Configuration data is divided into and accessed as independent entities called sections.

For example, there are separate sections for sites, logging, caching, and so on. Any configuration data contained in ApplicationHost.config is applied to all sites, applications, and virtual directories configured within IIS. At the virtual directory level, a web.config file defines application-specific configuration data, possibly by overriding other data already defined in ApplicationHost.config. Web.config files are stored at the root (physical directory) corresponding to the site, application, or virtual directory the configuration applies to.

For more information about IIS configuration, see the following:

The IIS configuration schema used to validate IIS configuration data is XML files stored in the IIS schema directory (typically, %windir%\System32\InetSrv\Config\Schema). The IIS configuration schema is not XSD. IIS configuration supports extensibility. New configuration sections can be directly integrated into the IIS configuration system, and the IIS configuration system's settings can be manipulated using the existing administration APIs.

The following are the main steps involved:

  • Define a new configuration section in an XML schema file.
  • Place the file in the IIS 7 schema directory (%windir%\System32\InetSrv\Config\Schema).
  • Register the new section in the IIS global configuration file (ApplicationHost.config).

IIS Host (WinRM) Configuration Setup and Details

This section describes the steps to be taken during setup to integrate and initialize IIS host configuration. Here, IIS host configuration refers to the configuration data required to run the WinRM service within IIS. The WinRM IIS extension module is an optional component that is installed using the Server Manager.

The IIS configuration section that defines the required configuration is called system.management.wsmanagement.config. Typically, the IIS host configuration is defined during setup. This can be done by creating a web.config file and adding the appropriate XML. Any changes to the web.config file require restarting the site hosting the WinRM service.

The following procedure describes setting up the WinRM IIS extension in detail.

To install the WinRM IIS extension

  1. In the Features Summary section of the Server Manager, click Add Features.
  2. In the Add Features Wizard, select WinRM IIS extension.
  3. Follow the wizard instructions, including installing the required software if any is indicated. For more information about using the Add Features Wizard, refer to the Server Manager online help.

Initializing WinRM Configuration for the Hosted Application

This step involves defining the IIS host configuration XML in the web.config file. This file resides in the physical directory corresponding to the virtual directory where the hosted application is configured. The XML content for the system.management.wsmanagement.config section should conform to the scheme defined in wsmanconfig_schema.xml; otherwise, the IIS Administration APIs will be unable to process it. The following is an example of XML content that could be contained in the web.config file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
  <system.management.wsmanagement.config>
   <OperationsConfiguration MaxEnvelopeSizeKB="150" 
                            MaxOperationTimeoutSeconds="60"  
                            MaxEnumerateIdleTimeoutSeconds="60"  
                            MaxSubscribeIdleTimeoutSeconds="60"  
                            MaxShellIdleTimeoutMinutes="15"
                            QuotaRefreshIntervalSeconds="900"
                            QuotaSystemWindowSeconds="2"
                            QuotaSystemWindowOperations-"1000"/>
    <PluginModules>
     <AuthorizationPlugin Name="Auth1" Filename="Auth.dll" SDKVersion="1" SupportsQuota="true"/>
     <OperationsPlugins>
      <Plugin Name="PL1" Filename="PL1.dll" SDKVersion="1" XmlRenderingType="text">
       <InitializationParameters>
        <Param name="myParam1" value="myValue1"/>
       </InitializationParameters>
       <Resources>
        <Resource ResourceUri="myUri1">
        <Capability Type="Shell"/>
        </Resource>
       </Resources>
      </Plugin>
      <Plugin Name="PL2" Filename="PL2.dll" SDKVersion="1" XmlRenderingType="text">
       <InitializationParameters/>
       <Resources>
        <Resource ResourceUri="myUri1">
         <Capability Type="Get"/>
         <Capability Type="Put"/>
         <Capability Type="Delete"/>
        </Resource>
       </Resources>
      </Plugin>
     </OperationsPlugins>
    </PluginModules>
   </OperationsConfiguration>
  </system.management.wsmanagement.config>
 </system.webServer>
</configuration>

The following list describes the XML elements in more detail and is followed by an example of a wsmanconfig_schema.xml file.

Element Description
OperationsConfiguration/MaxEnvelopeSizeKB The maximum size of the SOAP packets that the WinRM service will process. The default value is 150 KB.
OperationsConfiguration/MaxOperationTimeoutSeconds The maximum time-out interval for all operations. This value overrides any value that is received in a SOAP packet. If a provider exceeds this value, a time-out is sent to the client and the operation will be canceled. (Some operations, like enumerations, can keep an enumeration open after a time-out.) The default is 60 seconds.
OperationsConfiguration/MaxEnumerationIdleTimeoutSeconds The maximum time-out interval for enumerations. If the time between enumeration requests is greater than this value, the enumeration is canceled and the previously issued enumeration context is no longer valid. The default is 60 seconds.
OperationsConfiguration/MaxSubscribeIdleTimeoutSeconds The maximum time-out interval for Subscribe operations. The default is 60 seconds.
OperationsConfiguration/MaxShellIdleTimeoutMinutes The maximum time in minutes before an inactive remote shell is deleted. The default is 15 minutes.
OperationsConfiguration/QuotaRefreshIntervalSeconds The interval before the quota information for a user is refreshed. Pending requests for the specified user continue to execute under the previous authorization and quota context until the refresh is completed. The default is 900 seconds.
OperationsConfiguration/QuotaSystemWindowSeconds The duration of the system throttle sliding window. The default is 2 seconds.
OperationsConfiguration/QuotaSystemWindowOperations The number of operations that are admitted through the system throttle during the sliding window. The default is 1000 operations.
PlugInModules/AuthorizationPlugin This node is optional. An authorization plug-in allows a programmatic way of accepting or rejecting an inbound user based on different authentication schemes.
PlugInModules/AuthorizationPlugin/Name Specifies the display name to use for the plug-in. If an error is returned from the plug-in, this name will be put into the error XML that is returned to the client application. The name is not locale specific.
PlugInModules/AuthorizationPlugin/Filename Specifies the file name of the authorization plug-in. Any environment variables that are put in this entry will be expanded based on the identity that the IIS host is running under, such as Network Service. The default value for this entry is empty, which signifies that no authorization plug-in is used.
PlugInModules/AuthorizationPlugin/SDKVersion Specifies the version of the software development kit (SDK) for which a particular plug-in was written. This element must be set to 1.
PlugInModules/AuthorizationPlugin/SupportsQuota Specifies whether the authorization plug-in supports quotas.
PlugInModules/OperationsPlugins/Name Specifies the display name to use for the plug-in. If an error is returned from the plug-in, this name will be put into the error XML that is returned to the client application. The name is not locale specific.
PlugInModules/OperationsPlugins/FileName Specifies the file name of the operation plug-in. Any environment variables that are put in this entry will be expanded in the user's context when a request comes in. Each user could have a different version of the same environment variable, so each user could end up with a different plug-in. This entry cannot be blank and must point to a valid plug-in.
PlugInModules/OperationsPlugins/SDKVersion Specifies the version of the SDK for which a particular plug-in was written. This element must be set to 1.
PlugInModules/OperationsPlugins/XmlRenderingType Configures the format in which XML is passed to plug-ins through the WSMAN_DATA object. XmlRenderingType is set to text. Incoming XML data is contained in a WSMAN_DATA_TYPE_TEXT structure, which represents the XML as a PCWSTR memory buffer.
PlugInModules/OperationsPlugins/InitializationParameters This node is optional and allows a plug-in to configure extra XML that will be passed in to the WSManPluginStartup method. Most plug-ins will not need this extra information, but if a plug-in needs to be used under more than one scenario that requires different run-time semantics, this XML will give the plug-in the flexibility do this.
PlugInModules/OperationsPlugins/Resources Specifies a list of resource URIs that this plug-in supports. At least one ResourceUri entry must be specified; otherwise, the XML will be rejected.
PlugInModules/OperationsPlugins/Resources/Resource Represents a single resource URI configuration.
PlugInModules/OperationsPlugins/Resources/Resource/ResourceUri Specifies a single resource URI either in full or as a partial match string based on the ExactMatch attribute. If ExactMatch is not present, it defaults to False, which means the WinRM SOAP processor will do a partial match to the start of the resource URI and, if there is a match, pass it to the plug-in. The SupportsOptions attribute can be specified if this resource URI is allowed to have any options passed in. By default, no options are supported, and if any are present in the client request, an error will be returned. If options are supported by the plug-in, it is important that the plug-in returns the correct error if an option is present that the plug-in does not understand when the mustUnderstand flag is set to TRUE.
PlugInModules/OperationsPlugins/Resource/Capability Specifies a capability that is available on this resource URI. There will be one entry for each type of operation that it supports. The following options are available:
Get
Get operations are supported on the resource URI. The SupportFragment attribute is used if the get operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Put
Put operations are supported on the resource URI. The SupportFragment attribute is used if the put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Create
Create operations are supported on the resource URI. The SupportFragment attribute is used if the create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Delete
Delete operations are supported on the resource URI. The SupportFragment attribute is used if the delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Invoke
Invoke operations are supported on the resource URI. The SupportFragment attribute is not supported for invoke operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Enumerate
Enumerate operations are supported on the resource URI. The SupportFragment attribute is not supported for enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering, this attribute should be set to True. This capability is not valid for a resource URI if shell operations are also supported.
Subscribe
Subscribe operations are supported on the resource URI. The SupportFragment attribute is not supported for subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.
Shell
Shell operations are supported on the resource URI. The SupportFragment attribute is not supported for shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if any other operation capability is also supported. If a shell operation capability is configured for a resource URI, then get, put, create, delete, invoke, and enumerate operations are processed internally within the WinRM service to manage shells. As a result, the plug-in cannot deal with the operations itself.

Example wsmanconfig_schema.xml File

During set up, an XML file called wsmanconfig_schema.xml containing the following content is dropped in the IIS schema directory:

<configSchema>
 <sectionSchema name="system.webServer/system.management.wsmanagement.config">
  <element name="OperationsConfiguration">
   <attribute name="MaxEnvelopeSizeKB" 
              type="uint" 
              defaultValue="150" 
              validationType="integerRange" 
              validationParameter="32,4294967295"/>
   <attribute name="MaxOperationTimeoutSeconds" 
              type="uint" 
              defaultValue="60" 
              validationType="integerRange" 
              validationParameter="1,4294967295"/>
   <attribute name="MaxEnumerateIdleTimeoutSeconds" 
              type="uint" 
              defaultValue="60" 
              validationType="integerRange" 
              validationParameter="1,4294967295"/>
   <attribute name="MaxSubscribeIdleTimeoutSeconds" 
              type="uint" 
              defaultValue="60" 
              validationType="integerRange" 
              validationParameter="1,4294967295"/>
   <attribute name="MaxShellIdleTimeoutMinutes" 
              type="uint" 
              defaultValue="15" 
              validationType="integerRange" 
              validationParameter="0,4294967295"/>
   <attribute name="QuotaRefreshIntervalSeconds" 
              type="uint" 
              defaultValue="900" 
              validationType="integerRange" 
              validationParameter="0,4294967295"/>
   <attribute name="QuotaSystemWindowSeconds" 
              type="uint" 
              defaultValue="2" 
              validationType="integerRange" 
              validationParameter="0,4294967295"/>
   <attribute name="QuotaSystemWindowOperations" 
              type="uint" 
              defaultValue="1000" 
              validationType="integerRange" 
              validationParameter="0,4294967295"/>
  </element>
  <element name="PluginModules">
   <collection addElement="AuthorizationPlugin">
    <attribute name="Name" type="string" isUniqueKey="true" required="true" validationType="nonEmptyString"/>
    <attribute name="Filename" type="string" required="true" validationType="nonEmptyString"/>
    <attribute name="SDKVersion" type="uint" required="true"/>
    <attribute name="SupportsQuota" type="bool" defaultValue="false"/>
   </collection>
   <element name="OperationsPlugins">
    <collection addElement="Plugin">
     <attribute name="Name" type="string" isUniqueKey="true" required="true" validationType="nonEmptyString"/>
     <attribute name="Filename" type="string" required="true" validationType="nonEmptyString"/>
     <attribute name="SDKVersion" type="uint" required="true"/>
     <attribute name="XmlRenderingType" type="enum" defaultValue="text">
      <enum name="text" value="1"/>
      <enum name="XmlReader" value="2"/>
     </attribute>
     <attribute name="Enabled" type="bool" defaultValue="true"/>
     <element name="InitializationParameters">
      <collection addElement="Param">
       <attribute name="Name" type="string" isUniqueKey="true" required="true" validationType="nonEmptyString"/>
       <attribute name="Value" type="string" required="true" validationType="nonEmptyString"/>
      </collection>
     </element>
     <element name="Resources">
      <collection addElement="Resource">
       <attribute name="ResourceUri" type="string" isUniqueKey="true" required="true" validationType="nonEmptyString"/>
       <attribute name="SupportsOptions" type="bool" defaultValue="false"/>
       <attribute name="ExactMatch" type="bool" defaultValue="false"/>
       <collection addElement="Capability">
        <attribute name="Type" type="enum" isUniqueKey="true" required="true">
         <enum name="Get" value="1"/>
         <enum name="Put" value="2"/>
         <enum name="Create" value="3"/>
         <enum name="Delete" value="4"/>
         <enum name="Invoke" value="5"/>
         <enum name="Enumerate" value="6"/>
         <enum name="Subscribe" value="7"/>
         <enum name="Shell" value="8"/>
        </attribute>
        <attribute name="SupportsFragment" type="bool" default="false"/>
        <attribute name="SupportsFiltering" type="bool" default="false"/>
       </collection>
      </collection>
     </element>
    </collection>
   </element>
  </element>
 </sectionSchema>
</configSchema>

Reading IIS Host Configuration

The IIS host configuration is read during the SOAP processor startup process in the hosted application. Because web.config files can be manually edited and, therefore, are prone to schema validation errors, there can be issues when a configuration is read. During a configuration read or validation failure, the hosted application will fail to start and will return an appropriate error message to the client. An event will be logged containing a detailed description of what caused the failure.

Common failures include the following:

  • Access Denied
  • Invalid Configuration XML
  • No plug-in configured (at least one is required)

The standard plug-ins are not configured by default. They need to be explicitly configured in the web.config file before they will start receiving requests.

Enumerating Plug-ins on the WinRM Service

The following command demonstrates how to use the winrm utility to determine which plug-ins are available on the WinRM service: winrm enumerate winrm/config/plugin -format:pretty.