Edit

Share via

Many-To-One Mappings Rules <rules>

  • Article

Overview

The <rules> element of the <add> element specifies criteria for mapping client certificates with IIS so that many clients can use one certificate.

There are two fields from client certificates that can be used as criteria for many-to-one rules:

  • Issuer - This field specifies information about the certification authority (CA) that issued the client certificate.
  • Subject - This field specifies information about the entity to whom the client certificate was issued.

Each of these fields can contain common LDAP sub fields; for example:

  • CN = commonName (for example, "Nancy Davolio")
  • OU = organizationalUnitName (for example, "Sales")
  • O = organizationName (for example, "Contoso")
  • L = localityName (for example, "Redmond")
  • S = stateOrProvinceName (for example, "WA")
  • C = countryName (for example, "US")

To create a mapping, you create a rule based on a field/subfield pair for a specific value. For example, you could create a rule that matched the issuer's O subfield with Contoso to allow access to all clients with certificates that were issued by the Contoso CA. This effectively eliminates client connections from any clients that are not part of the Contoso organization.

Compatibility

Version Notes
IIS 10.0 The <rules> element was not modified in IIS 10.0.
IIS 8.5 The <rules> element was not modified in IIS 8.5.
IIS 8.0 The <rules> element was not modified in IIS 8.0.
IIS 7.5 The <rules> element was not modified in IIS 7.5.
IIS 7.0 The <rules> element of the <add> element was introduced in IIS 7.0.
IIS 6.0 The <manyToOneMappings> element replaces the IIS 6.0 IIsCertMapper metabase object.

Setup

The <iisClientCertificateMappingAuthentication> 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 IIS Client Certificate Mapping Authentication. Click Next.
    Screenshot of the Server Roles page with Security expanded in the menu. I I S Client Certificate Mapping Authentication is highlighted and 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 IIS Client Certificate Mapping Authentication.
    Screenshot of the Windows Features dialog box. I I S Client Certificate Mapping Authentication is 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 IIS Client Certificate Mapping Authentication, and then click Next.
    Screenshot of the Role Services Page with I I S Client Certificate Mapping Authentication 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 select IIS Client Certificate Mapping Authentication, and then click OK.
    Screenshot of the Windows Features dialog box with I I S Client Certificate Mapping Authentication highlighted.

How To

There is no user interface for configuring IIS Client Certificate Mapping authentication for IIS 7. For examples of how to configure IIS Client Certificate Mapping authentication programmatically, see the Code Samples section of this document.

Configuration

Attributes

None.

Child Elements

Element Description
add Optional element.

Adds a rule to the collection of rules.
clear Optional element.

Removes all references to rules from the rules collection.

Configuration Sample

The following configuration sample performs the following actions for the Default Web Site:

  • Enables IIS Client Certificate Mapping authentication using many-to-one certificate mapping.
  • Creates a many-to-one certificate mapping rule for a user account based on the organization field in the subject of the client certificate matching Contoso.
  • Configures the site to require SSL and to negotiate client certificates.
<location path="Default Web Site">
   <system.webServer>
      <security>
         <authentication>
            <windowsAuthentication enabled="false" />
            <anonymousAuthentication enabled="false" />
            <digestAuthentication enabled="false" />
            <basicAuthentication enabled="false" />
            <iisClientCertificateMappingAuthentication enabled="true"
                  manyToOneCertificateMappingsEnabled="true">
               <manyToOneMappings>
                  <add name="Contoso Employees"
                        enabled="true"
                        permissionMode="Allow"
                        userName="Username"
                        password="[enc:AesProvider:57686f6120447564652c2049495320526f636b73:enc]">
                     <rules>
                        <add certificateField="Subject"
                           certificateSubField="O"
                           matchCriteria="Contoso"
                           compareCaseSensitive="true" />
                     </rules>
                  </add>
               </manyToOneMappings>
            </iisClientCertificateMappingAuthentication>
         </authentication>
         <access sslFlags="Ssl, SslNegotiateCert" />
      </security>
   </system.webServer>
</location>

Sample Code

The following code samples perform the following actions for the Default Web Site:

  • Enable IIS Client Certificate Mapping authentication using many-to-one certificate mapping.
  • Create a many-to-one certificate mapping rule for a user account based on the organization field in the subject of the client certificate matching Contoso.
  • Configure the site to require SSL and to negotiate client certificates.

AppCmd.exe

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

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/iisClientCertificateMappingAuthentication /+"manyToOneMappings.[name='Contoso Employees',enabled='True',permissionMode='Allow',userName='Username',password='Password']" /commit:apphost

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/iisClientCertificateMappingAuthentication /+"manyToOneMappings.[name='Contoso Employees'].rules.[certificateField='Subject',certificateSubField='O',matchCriteria='Contoso',compareCaseSensitive='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 iisClientCertificateMappingAuthenticationSection = config.GetSection("system.webServer/security/authentication/iisClientCertificateMappingAuthentication", "Default Web Site");
         iisClientCertificateMappingAuthenticationSection["enabled"] = true;
         iisClientCertificateMappingAuthenticationSection["manyToOneCertificateMappingsEnabled"] = true;

         ConfigurationElementCollection manyToOneMappingsCollection = iisClientCertificateMappingAuthenticationSection.GetCollection("manyToOneMappings");
         ConfigurationElement addElement = manyToOneMappingsCollection.CreateElement("add");
         addElement["name"] = @"Contoso Employees";
         addElement["enabled"] = true;
         addElement["permissionMode"] = @"Allow";
         addElement["userName"] = @"Username";
         addElement["password"] = @"Password";

         ConfigurationElementCollection rulesCollection = addElement.GetCollection("rules");
         ConfigurationElement addElement1 = rulesCollection.CreateElement("add");
         addElement1["certificateField"] = @"Subject";
         addElement1["certificateSubField"] = @"O";
         addElement1["matchCriteria"] = @"Contoso";
         addElement1["compareCaseSensitive"] = true;
         rulesCollection.Add(addElement1);
         manyToOneMappingsCollection.Add(addElement);

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

      Dim manyToOneMappingsCollection As ConfigurationElementCollection = iisClientCertificateMappingAuthenticationSection.GetCollection("manyToOneMappings")
      Dim addElement As ConfigurationElement = manyToOneMappingsCollection.CreateElement("add")
      addElement("name") = "Contoso Employees"
      addElement("enabled") = True
      addElement("permissionMode") = "Allow"
      addElement("userName") = "Username"
      addElement("password") = "Password"

      Dim rulesCollection As ConfigurationElementCollection = addElement.GetCollection("rules")
      Dim addElement1 As ConfigurationElement = rulesCollection.CreateElement("add")
      addElement1("certificateField") = "Subject"
      addElement1("certificateSubField") = "O"
      addElement1("matchCriteria") = "Contoso"
      addElement1("compareCaseSensitive") = True
      rulesCollection.Add(addElement1)
      manyToOneMappingsCollection.Add(addElement)

      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 iisClientCertificateMappingAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/iisClientCertificateMappingAuthentication", "MACHINE/WEBROOT/APPHOST/Default Web Site");
iisClientCertificateMappingAuthenticationSection.Properties.Item("enabled").Value = true;
iisClientCertificateMappingAuthenticationSection.Properties.Item("manyToOneCertificateMappingsEnabled").Value = true;

var manyToOneMappingsCollection = iisClientCertificateMappingAuthenticationSection.ChildElements.Item("manyToOneMappings").Collection;
var addElement = manyToOneMappingsCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "Contoso Employees";
addElement.Properties.Item("enabled").Value = true;
addElement.Properties.Item("permissionMode").Value = "Allow";
addElement.Properties.Item("userName").Value = "Username";
addElement.Properties.Item("password").Value = "Password";

var rulesCollection = addElement.ChildElements.Item("rules").Collection;
var addElement1 = rulesCollection.CreateNewElement("add");
addElement1.Properties.Item("certificateField").Value = "Subject";
addElement1.Properties.Item("certificateSubField").Value = "O";
addElement1.Properties.Item("matchCriteria").Value = "Contoso";
addElement1.Properties.Item("compareCaseSensitive").Value = true;
rulesCollection.AddElement(addElement1);
manyToOneMappingsCollection.AddElement(addElement);

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 iisClientCertificateMappingAuthenticationSection = adminManager.GetAdminSection("system.webServer/security/authentication/iisClientCertificateMappingAuthentication", "MACHINE/WEBROOT/APPHOST/Default Web Site")
iisClientCertificateMappingAuthenticationSection.Properties.Item("enabled").Value = True
iisClientCertificateMappingAuthenticationSection.Properties.Item("manyToOneCertificateMappingsEnabled").Value = True

Set manyToOneMappingsCollection = iisClientCertificateMappingAuthenticationSection.ChildElements.Item("manyToOneMappings").Collection
Set addElement = manyToOneMappingsCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "Contoso Employees"
addElement.Properties.Item("enabled").Value = True
addElement.Properties.Item("permissionMode").Value = "Allow"
addElement.Properties.Item("userName").Value = "Username"
addElement.Properties.Item("password").Value = "Password"

Set rulesCollection = addElement.ChildElements.Item("rules").Collection
Set addElement1 = rulesCollection.CreateNewElement("add")
addElement1.Properties.Item("certificateField").Value = "Subject"
addElement1.Properties.Item("certificateSubField").Value = "O"
addElement1.Properties.Item("matchCriteria").Value = "Contoso"
addElement1.Properties.Item("compareCaseSensitive").Value = True
rulesCollection.AddElement(addElement1)
manyToOneMappingsCollection.AddElement(addElement)

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

adminManager.CommitChanges()