Edit

Share via

Windows Extended Protection <extendedProtection>

  • Article

Overview

The <extendedProtection> element specifies the settings that configure the extended protection for Windows authentication in IIS 7.5.

Extended protection enhances the existing Windows authentication functionality in order to mitigate authentication relay or "man in the middle" attacks. This mitigation is accomplished by using security information that is implemented through two security mechanisms:

  • Channel-binding information that is specified through a Channel Binding Token (CBT), which is primarily used for SSL connections.
  • Service-binding information that is specified through a Service Principle Name (SPN), which is primarily used for connections that do not use SSL, or when a connection is established through a scenario that provides SSL-offloading, such as a proxy server or load-balancer.

The <extendedProtection> element may contain a collection of <spn> elements, each of which contains a unique SPN for the service binding information. Each SPN represents a unique endpoint in the connection path, which may be a Fully Qualified Domain Name (FQDN) or NetBIOS name of the destination server or a proxy server. For example, if a client is connecting to a destination server through a proxy server, the SPN collection on the destination server would need to contain the SPN for the proxy server. Each SPN in the collection must be prefixed with "HTTP," so the resulting SPN for "www.contoso.com" would be "HTTP/www.contoso.com."

There are two attributes of the <extendedProtection> element that configure the channel-binding and additional behavior for IIS extended protection:

  • The tokenChecking attribute configures the behavior for checking for channel-binding tokens. The possible values for this attribute are:

    Name Description
    None This value specifies that IIS will not perform channel-binding token checking. This setting emulates the behavior that existed before extended protection.

    The numerical value is 0.
    Allow This value specifies that channel-binding token checking is enabled, but not required. This setting allows secure communication with clients that support extended protection, but still supports clients that are not capable of using extended protection.

    The numerical value is 1.
    Require This value specifies that channel-binding token checking is required. This setting does not provide support for clients that do not support extended protection.

    The numerical value is 2.

  • The flags attribute configures additional behavior for extended protection. The possible flags are:

    Name Description
    None This flag specifies that no additional behavior is enabled for extended protection. (For example, no proxy server is being used and SPN checking is enabled and requires FQDNs.)

    The numerical value is 0.
    Proxy This flag specifies that part of the communication path will be through a proxy, or that the client is connecting directly to the destination server over HTTP.

    The numerical value is 1.
    NoServiceNameCheck This flag specifies that SPN checking is disabled; this flag should not be used in scenarios where only SPNs are being checked.

    The numerical value is 2.
    AllowDotlessSpn This flag specifies that SPNs are not required to be FQDNs. Setting this flag allows NetBIOS-based SPNs. Note: Setting this flag is not a secure scenario; non-FQDN-based names are vulnerable to name resolution poisoning attacks.

    The numerical value is 4.
    ProxyCohosting This flag specifies that the entire client-to-server communication path will use HTTP only; no part of the communication path will use SSL, and SPN checking will be used. Note: When you specify this flag, you must also specify the Proxy flag.

    The numerical value is 32.

Extended Protection Scenarios

Consider the following example scenarios:

  • In each of the following scenarios, you could also specify the AllowDotlessSpn flag if your networking environment supports NetBIOS-based SPNs; however, NetBIOS-based SPNs are not secure.
  • For each of the following scenarios where SPN checking will be used and channel-binding token checking will not be used, you should not specify the NoServiceNameCheck flag.
Scenario Flags Description
Client connects directly to destination server using HTTP Proxy, ProxyCohosting SPN checking will be used and channel-binding token checking will not be used.
Client connects directly to destination server using SSL None Channel-binding token checking is used and SPN checking is not used.
Client connects to destination server through a proxy server using HTTP for the entire path Proxy, ProxyCohosting SPN checking will be used and channel-binding token checking will not be used.
Client connects to destination server through a proxy server using SSL for the entire path Proxy SPN checking will be used and channel-binding token checking will not be used.
Client connects to proxy server using SSL and proxy server connects to the destination server using HTTP (SSL off-loading) Proxy SPN checking will be used and channel-binding token checking will not be used.

Additional Information

More information about Extended Protection is available in the following topic:

Integrated Windows Authentication with Extended Protection

Service Principal Names

Compatibility

Version Notes
IIS 10.0 The <extendedProtection> element was not modified in IIS 10.0.
IIS 8.5 The <extendedProtection> element was not modified in IIS 8.5.
IIS 8.0 The <extendedProtection> element was not modified in IIS 8.0.
IIS 7.5 The <extendedProtection> element was introduced in IIS 7.5.
IIS 7.0 N/A
IIS 6.0 N/A

Setup

The default installation of IIS 7 and later does not include the Windows authentication role service. To use Windows authentication on IIS, you must install the role service, disable Anonymous authentication for your Web site or application, and then enable Windows authentication for the site or application.

Note

After you install the role service, IIS 7 commits the following configuration settings to the ApplicationHost.config file.

<windowsAuthentication enabled="false" />

Windows Server 2012 or Windows Server 2012 R2

  1. On the taskbar, click Server Manager.
  2. In Server Manager, click the Manage menu, and then click Add Roles and Features.
  3. In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.
  4. On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Security, and then select Windows Authentication. Click Next.
    Screenshot of the Server Roles page. The Windows Authentication option is selected and highlighted. .
  5. On the Select features page, click Next.
  6. On the Confirm installation selections page, click Install.
  7. On the Results page, click Close.

Windows 8 or Windows 8.1

  1. On the Start screen, move the pointer all the way to the lower left corner, right-click the Start button, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows features on or off.
  3. Expand Internet Information Services, expand World Wide Web Services, expand Security, and then select Windows Authentication.
    Screenshot of the Programs and Features navigation tree. The Windows Authentication option is selected and highlighted.
  4. Click OK.
  5. Click Close.

Windows Server 2008 or Windows Server 2008 R2

  1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
  2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
  3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
  4. On the Select Role Services page of the Add Role Services Wizard, select Windows Authentication, and then click Next.
    Screenshot of the Select Role Services page. The Security option is expanded. The Windows Authentication option is selected and highlighted.
  5. On the Confirm Installation Selections page, click Install.
  6. On the Results page, click Close.

Windows Vista or Windows 7

  1. On the taskbar, click Start, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
  3. Expand Internet Information Services, then World Wide Web Services, then Security.
  4. Select Windows Authentication, and then click OK.
    Screenshot of the Programs and Features navigation tree. Windows Authentication is highlighted and selected. The Security folder is expanded.

How To

How to enable Extended Protection for Windows authentication

  1. Open Internet Information Services (IIS) Manager:

    • If you are using Windows Server 2012 or Windows Server 2012 R2:

      • On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows 8 or Windows 8.1:

      • Hold down the Windows key, press the letter X, and then click Control Panel.
      • Click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

    • If you are using Windows Server 2008 or Windows Server 2008 R2:

      • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

    • If you are using Windows Vista or Windows 7:

      • On the taskbar, click Start, and then click Control Panel.
      • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.

  2. In the Connections pane, expand the server name, expand Sites, and then the site, application, or Web service for which you want to enable Extended Protection for Windows authentication.

  3. Scroll to the Security section in the Home pane, and then double-click Authentication.

  4. In the Authentication pane, select Windows Authentication.

  5. Click Enable in the Actions pane.
    Screenshot of the Authentication page. Windows Authentication is highlighted. The Enable button is found in the Actions pane.

  6. Click Advanced Settings in the Actions pane.

  7. When the Advanced Settings dialog box appears, select one of the following options in the Extended Protection drop-down menu:

    • Select Accept if you want to enable extended protection while providing down-level support for clients that do not support extended protection.
    • Select Required if you want to enable extended protection without providing down-level support.
      Screenshot of the Advanced Settings dialog box. In the Extended Protection drop down menu, the Accept option is highlighted.

  8. Click OK to close the Advanced Settings dialog box.

Configuration

The <extendedProtection> element is configurable at the site, application, or virtual directory level in the ApplicationHost.config file.

Attributes

Attribute Description
flags Optional flags attribute.

Specifies the additional behavior settings for extended protection.

The flags attribute can be a combination of the following values; the default value is None.
Name Description
None

This flag specifies that no additional behavior is enabled for extended protection. (For example, no proxy server is being used and SPN checking is enabled and requires FQDNs.)

The numerical value is 0.

Proxy

This flag specifies that part of the communication path will be through a proxy, or that the client is connecting directly to the destination server over HTTP.

The numerical value is 1.

NoServiceNameCheck

This flag specifies that SPN checking is disabled; this flag should not be used in scenarios where only SPNs are being checked.

The numerical value is 2.

AllowDotlessSpn

This flag specifies that SPNs are not required to be FQDNs. Setting this flag allows NetBIOS-based SPNs. Note: Setting this flag is not a secure scenario; non-FQDN-based names are vulnerable to name resolution poisoning attacks.

The numerical value is 4.

ProxyCohosting

This flag specifies that the entire client-to-server communication path will use HTTP only; no part of the communication path will use SSL, and SPN checking will be used. Note: When you specify this flag, you must also specify the Proxy flag.

The numerical value is 32.
tokenChecking Optional enum attribute.

Specifies the behavior for checking channel-binding information.

The tokenChecking attribute can be one of the following values; the default value is None.
Name Description
None

This value specifies that IIS will not perform channel-binding token checking. This setting emulates the behavior that existed before extended protection.

The numerical value is 0.

Allow

This value specifies that channel-binding token checking is enabled, but not required. This setting allows secure communication with clients that support extended protection, but still supports clients that are not capable of using extended protection.

The numerical value is 1.

Require

This value specifies that channel-binding token checking is required. This setting does not provide support for clients that do not support extended protection.

The numerical value is 2.

Child Elements

Element Description
spn Adds a SPN to the collection.
clearSpns Clears the collection of SPNs.
removeSpn Removes a SPN from the collection.

Configuration Sample

The following sample displays a <extendedProtection> element that demonstrates enabling Windows authentication with extended protection for the Default Web Site, and adds two SPN entries to the collection of SPNs.

<location path="Default Web Site">
   <system.webServer>
      <security>
         <authentication>
            <windowsAuthentication enabled="true">
               <extendedProtection tokenChecking="Allow" flags="None">
                  <spn name="HTTP/www.contoso.com" />
                  <spn name="HTTP/contoso.com" />
               </extendedProtection>
            </windowsAuthentication>
         </authentication>
      </security>
   </system.webServer>
</location>

Sample Code

The following examples demonstrate configuring Windows authentication with extended protection for the Default Web Site, and adds two SPN entries to the collection of SPNs.

AppCmd.exe

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/windowsAuthentication /enabled:"True" /commit:apphost

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/windowsAuthentication /extendedProtection.tokenChecking:"Allow" /extendedProtection.flags:"None" /commit:apphost

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/windowsAuthentication /+"extendedProtection.[name='HTTP/www.contoso.com']" /commit:apphost

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/windowsAuthentication /+"extendedProtection.[name='HTTP/contoso.com']" /commit:apphost

Note

You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();

         ConfigurationSection windowsAuthenticationSection = config.GetSection("system.webServer/security/authentication/windowsAuthentication", "Default Web Site");
         windowsAuthenticationSection["enabled"] = true;

         ConfigurationElement extendedProtectionElement = windowsAuthenticationSection.GetChildElement("extendedProtection");
         extendedProtectionElement["tokenChecking"] = @"Allow";
         extendedProtectionElement["flags"] = @"None";

         ConfigurationElementCollection extendedProtectionCollection = extendedProtectionElement.GetCollection();

         ConfigurationElement spnElement = extendedProtectionCollection.CreateElement("spn");
         spnElement["name"] = @"HTTP/www.contoso.com";
         extendedProtectionCollection.Add(spnElement);

         ConfigurationElement spnElement1 = extendedProtectionCollection.CreateElement("spn");
         spnElement1["name"] = @"HTTP/contoso.com";
         extendedProtectionCollection.Add(spnElement1);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration

      Dim windowsAuthenticationSection As ConfigurationSection = config.GetSection("system.webServer/security/authentication/windowsAuthentication", "Default Web Site")
      windowsAuthenticationSection("enabled") = True

      Dim extendedProtectionElement As ConfigurationElement = windowsAuthenticationSection.GetChildElement("extendedProtection")
      extendedProtectionElement("tokenChecking") = "Allow"
      extendedProtectionElement("flags") = "None"

      Dim extendedProtectionCollection As ConfigurationElementCollection = extendedProtectionElement.GetCollection

      Dim spnElement As ConfigurationElement = extendedProtectionCollection.CreateElement("spn")
      spnElement("name") = "HTTP/www.contoso.com"
      extendedProtectionCollection.Add(spnElement)

      Dim spnElement1 As ConfigurationElement = extendedProtectionCollection.CreateElement("spn")
      spnElement1("name") = "HTTP/contoso.com"
      extendedProtectionCollection.Add(spnElement1)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var windowsAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/windowsAuthentication", "MACHINE/WEBROOT/APPHOST/Default Web Site");
windowsAuthenticationSection.Properties.Item("enabled").Value = true;

var extendedProtectionElement = windowsAuthenticationSection.ChildElements.Item("extendedProtection");
extendedProtectionElement.Properties.Item("tokenChecking").Value = "Allow";
extendedProtectionElement.Properties.Item("flags").Value = "None";

var extendedProtectionCollection = extendedProtectionElement.Collection;

var spnElement = extendedProtectionCollection.CreateNewElement("spn");
spnElement.Properties.Item("name").Value = "HTTP/www.contoso.com";
extendedProtectionCollection.AddElement(spnElement);

var spnElement1 = extendedProtectionCollection.CreateNewElement("spn");
spnElement1.Properties.Item("name").Value = "HTTP/contoso.com";
extendedProtectionCollection.AddElement(spnElement1);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set windowsAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/windowsAuthentication", "MACHINE/WEBROOT/APPHOST/Default Web Site")
windowsAuthenticationSection.Properties.Item("enabled").Value = True

Set extendedProtectionElement = windowsAuthenticationSection.ChildElements.Item("extendedProtection")
extendedProtectionElement.Properties.Item("tokenChecking").Value = "Allow"
extendedProtectionElement.Properties.Item("flags").Value = "None"

Set extendedProtectionCollection = extendedProtectionElement.Collection

Set spnElement = extendedProtectionCollection.CreateNewElement("spn")
spnElement.Properties.Item("name").Value = "HTTP/www.contoso.com"
extendedProtectionCollection.AddElement(spnElement)

Set spnElement1 = extendedProtectionCollection.CreateNewElement("spn")
spnElement1.Properties.Item("name").Value = "HTTP/contoso.com"
extendedProtectionCollection.AddElement(spnElement1)

adminManager.CommitChanges()