Client Certificate Mapping Authentication <clientCertificateMappingAuthentication>

Overview

<clientCertificateMappingAuthentication> element of the <authentication> element specifies whether client certificate mapping using Active Directory is enabled for Internet Information Services (IIS) 7.

Note

Client Certificate Mapping authentication using Active Directory differs from Client Certificate Mapping authentication using IIS in the following ways:

  • Client Certificate Mapping authentication using Active Directory - this method of authentication requires that the IIS 7 server is a member of an Active Directory domain, and user accounts are stored in Active Directory. This method of client certificate authentication has reduced performance due to the round-trip to the Active Directory server.
  • IIS Client Certificate Mapping authentication - this method of authentication does not require Active Directory and therefore works with standalone servers. This method of client certificate authentication has increased performance, but required more configuration and requires access to client certificates in order to create mappings.

For more information, see Configuring Authentication in IIS 7.0 on the Microsoft TechNet Web site.

Compatibility

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

Setup

The <clientCertificateMappingAuthentication> element is not available on the default installation of IIS 7 and later. To install it, use the following steps.

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 Client Certificate Mapping Authentication. Click Next.
    Image of Web Server and Security pane expanded with Client Certificate Mapping Authentication selected. .
  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 Client Certificate Mapping Authentication.
    Screenshot of World Wide Web Services pane expanded and Client Certificate Mapping Authentication selected.
  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 Client Certificate Mapping Authentication, and then click Next.
    Image of Select Role Services page with Security pane expanded and Client Certificate Mapping Authentication selected.
  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 select Client Certificate Mapping Authentication, and then click OK.
    Screenshot of Internet Information Services pane expanded and Client Certificated Mapping Authentication highlighted.

How To

How to enable client certificate mapping authentication for a server

  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, click the server name.

  3. In the server's Home pane, double-click Authentication.
    Screenshot of servers Home pane displaying Authentication highlighted.

  4. On the Authentication page, click Enable in the Actions pane.
    Image of Actions pane in Authentication page displaying Active Directory Client Certificate Authentication option highlighted.

Configuration

Attributes

Attribute Description
enabled Optional Boolean attribute.

Specifies whether Client Certificate Mapping authentication using Active Directory is enabled. For this setting to take effect, you must set this attribute with IIS Manager. If you use any other method to set this attribute, you must restart the Web server for the setting to take effect.

The default value is false.

Child Elements

None.

Configuration Sample

The following configuration sample enables client certificate mapping authentication using Active Directory for the Default Web Site, and configures the site to require SSL and negotiate client certificates.

<location path="Default Web Site">
   <system.webServer>
      <security>
         <access sslFlags="Ssl, SslNegotiateCert" />
          <authentication>
            <windowsAuthentication enabled="false" />
            <anonymousAuthentication enabled="false" />
            <digestAuthentication enabled="false" />
            <basicAuthentication enabled="false" />
            <clientCertificateMappingAuthentication enabled="true" />
         </authentication>
     </security>
   </system.webServer>
</location>

Sample Code

The following code samples enable client certificate mapping authentication using Active Directory for the Default Web Site, and configure the site to require SSL and negotiate client certificates.

AppCmd.exe

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

appcmd.exe set config "Default Web Site" -section:system.webServer/security/access /sslFlags:"Ssl, SslNegotiateCert" /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 clientCertificateMappingAuthenticationSection = config.GetSection("system.webServer/security/authentication/clientCertificateMappingAuthentication", "Default Web Site");
         clientCertificateMappingAuthenticationSection["enabled"] = true;

         ConfigurationSection accessSection = config.GetSection("system.webServer/security/access", "Default Web Site");
         accessSection["sslFlags"] = @"Ssl, SslNegotiateCert";

         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 clientCertificateMappingAuthenticationSection As ConfigurationSection = config.GetSection("system.webServer/security/authentication/clientCertificateMappingAuthentication", "Default Web Site")
      clientCertificateMappingAuthenticationSection("enabled") = True

      Dim accessSection As ConfigurationSection = config.GetSection("system.webServer/security/access", "Default Web Site")
      accessSection("sslFlags") = "Ssl, SslNegotiateCert"

      serverManager.CommitChanges()
   End Sub

End Module

JavaScript

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

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

var accessSection = adminManager.GetAdminSection("system.webServer/security/access", "MACHINE/WEBROOT/APPHOST/Default Web Site");
accessSection.Properties.Item("sslFlags").Value = "Ssl, SslNegotiateCert";

adminManager.CommitChanges();

VBScript

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

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

Set accessSection = adminManager.GetAdminSection("system.webServer/security/access", "MACHINE/WEBROOT/APPHOST/Default Web Site")
accessSection.Properties.Item("sslFlags").Value = "Ssl, SslNegotiateCert"

adminManager.CommitChanges()