Configuring Many-to-One Client Certificate Mappings for Internet Information Services (IIS) 7.0 and 7.5

Article ID: 2026113 - View products that this article applies to.
Expand all | Collapse all

Many-to-One Client Certificate mapping is used by Internet Information Services (IIS) to associate an end-user to a Windows account when the client certificate is used for user authentication. The user's session is executed under the context of this mapped Windows account by IIS. For this to work as expected, you need to ensure that the certificate-to-account mapping is configured correctly in IIS.

In IIS 6.0, users had the option to configure Many-to-One client certificate mapping through the IIS Manager User Interface. In IIS 7.0 and 7.5, that interface does not exist for either One-to-One or Many-to-One mappings. This article talks about using the Configuration Editor feature of IIS to configure Many-to-One client certificate mappings.

 

NOTE: For information about using the Configuration Editor to configure One-to-One client certificate mappings, please see the following article:

 

Configuring One-to-One Client Certificate Mappings
http://learn.iis.net/page.aspx/478/configuring-one-to-one-client-certificate-mappings/

 

 

IIS 7.0/7.5 Schema


This is the schema for the IIS Client Certificate Mapping authentication feature in IIS 7.0 and IIS 7.5:


 

<sectionSchema name="system.webServer/security/authentication/iisClientCertificateMappingAuthentication">
    <attribute name="enabled" type="bool" defaultValue="false" />
    <attribute name="manyToOneCertificateMappingsEnabled" type="bool" defaultValue="true" />
    ...
    <element name="manyToOneMappings">
      <collection addElement="add" clearElement="clear">
        <attribute name="name" type="string" required="true" isUniqueKey="true" validationType="nonEmptyString" />
        <attribute name="description" type="string" />
        <attribute name="enabled" type="bool" defaultValue="true" />
        <attribute name="permissionMode" type="enum" defaultValue="Allow">
          <enum name="Allow" value="1" />
          <enum name="Deny" value="2" />
        </attribute>
        <element name="rules">
          <collection addElement="add" clearElement="clear">
            <attribute name="certificateField" type="enum" required="true" isCombinedKey="true">
              <enum name="Subject" value="1" />
              <enum name="Issuer" value="2" />
            </attribute>
            <attribute name="certificateSubField" type="string" caseSensitive="true" required="true" isCombinedKey="true" />
            <attribute name="matchCriteria" type="string" caseSensitive="true" required="true" isCombinedKey="true" />
            <attribute name="compareCaseSensitive" type="bool" isCombinedKey="true" defaultValue="true" />
          </collection>
        </element>
        <attribute name="userName" type="string" validationType="nonEmptyString" />
        <attribute name="password" type="string" caseSensitive="true" encrypted="true" defaultValue="[enc:AesProvider::enc]" />
      </collection>
    </element>
    ...
  </sectionSchema>

  

Prerequisites

These are the prerequisites needed for this walkthrough: 

  1. You have installed the IIS Client Certificate Mapping module on the IIS server.
  2. A Web Site is configured with an HTTPS binding which can accept SSL connections.
  3. You have a client certificate installed on the client.
  4. The IIS 7 Administration Pack is installed on the IIS 7.0 server. NOTE: Configuration Editor is shipped by default on IIS 7.5.

 

Walkthrough

Step 1:

1. Launch the IIS manager and select the web site to be configured for client certificate authentication.

2. In the Features view select Configuration Editor under the Management section.


3. Go to "system.webServer/security/authentication/iisClientCertificateMappingAuthentication" in the drop-down box as shown below:

You will see a window to configure Many-to-One or One-to-One certificate mappings here. This is the UI provided through Configuration Editor from where you can set up all of the mapping configurations.

4. Modify the properties through this GUI.

  • Set enabled to true
  • Set manyToOneCertificateMappingsEnabled to True
  • Select manyToOneMappings and click on the ellipsis button to launch a new window for configuring mappings.

5. Under this new window click to Add a new item. You can modify the properties from within the window as shown below:

6. Click on the ellipsis button for rules which will give you the option to add multiple patterns for matching based on the certificate properties.

 

 

In these example images, there are two entries for rules for mapping the certificate. First, there are the Subject and Issuer fields in the certificate.  Second, there is the matchcriteria property the map the certificate to the account mydomain\testuser.

In the image below, the final mapping for a specific windows account is illustrated. As you can see there are two entries for rules for this account.

Similarly, you can have other mappings for the accounts based on the fields “Issuer” and “Subject” in the Certificate.

 

Appendix

So far what has been illustrated is achieved using the Configuration Editor, which provides a graphical interface to easily set the configuration.  You can achieve the same thing using APPCMD.exe commands, and in fact the Configuration Editor does the same thing in the background and adds these settings into the ApplicationHost.config file.

Configuration Editor also gives you an option to run these commands manually, and it generates the scripts to achieve this from inside the UI itself:

 

 

These are the code snippets to perform the same steps as above to configure the certificate mapping.  They were was generated using Configuration Editor's Script Generation feature.

 

AppCmd instructions

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='My 1st  Mapping',description='1st User Mapping',userName='mydomain\testuser',password='abcdef']" /commit:apphost
appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/iisClientCertificateMappingAuthentication /+"manyToOneMappings.[name='My 1st  Mapping',description='1st User Mapping',userName='mydomain\testuser',password='abcdef'].rules.[certificateField='Subject',certificateSubField='CN',matchCriteria='Test User']" /commit:apphost

 

 

C# Code 

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"] = @"My 1st  Mapping";
            addElement["description"] = @"1st User Mapping";
            addElement["userName"] = @"mydomain\testuser";
            addElement["password"] = @"abcdef";            
            ConfigurationElementCollection rulesCollection = addElement.GetCollection("rules");            
            ConfigurationElement addElement1 = rulesCollection.CreateElement("add");
            addElement1["certificateField"] = @"Subject";
            addElement1["certificateSubField"] = @"CN";
            addElement1["matchCriteria"] = @"Test User";
            rulesCollection.Add(addElement1);
            manyToOneMappingsCollection.Add(addElement);            
            serverManager.CommitChanges();
        }
    }
}

 

Scripting (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 = "My 1st  Mapping";
addElement.Properties.Item("description").Value = "1st User Mapping";
addElement.Properties.Item("userName").Value = "mydomain\\testuser";
addElement.Properties.Item("password").Value = "abcdef";
var rulesCollection = addElement.ChildElements.Item("rules").Collection;
var addElement1 = rulesCollection.CreateNewElement("add");
addElement1.Properties.Item("certificateField").Value = "Subject";
addElement1.Properties.Item("certificateSubField").Value = "CN";
addElement1.Properties.Item("matchCriteria").Value = "Test User";
rulesCollection.AddElement(addElement1);
manyToOneMappingsCollection.AddElement(addElement);
adminManager.CommitChanges();
 

 

Note This is a "FAST PUBLISH" article created directly from within the Microsoft support organization. The information contained herein is provided as-is in response to emerging issues. As a result of the speed in making it available, the materials may include typographical errors and may be revised at any time without notice. See Terms of Use for other considerations.

Properties

Article ID: 2026113 - Last Review: June 1, 2010 - Revision: 13.0
APPLIES TO
  • Microsoft Internet Information Services 7.0
  • Microsoft Internet Information Services 7.5
Keywords: 
KB2026113

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com