Configuring Many-to-One client certificate mappings for IIS

2024-12-17

This article introduces how to use the Configuration Editor feature in Microsoft Internet Information Services (IIS) to configure Many-to-One client certificate mappings.

Original product version: Internet Information Services
Original KB number: 2026113

Introduction

Many-to-One Client Certificate mapping is used by 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. To work as expected, you need to ensure the certificate-to-account mapping is configured correctly in IIS.

In the current version of IIS, the IIS Manager User Interface doesn't exist for either One-to-One or Many-to-One certificate 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, see Configuring One-to-One Client Certificate Mappings.

IIS schema

Here's the schema for the IIS Client Certificate Mapping authentication feature in IIS:

<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

Here are the prerequisites needed for this walk-through:

You have installed the IIS Client Certificate Mapping module on the IIS server.
A web site is configured with a Hypertext Transfer Protocol Secure (HTTPS) binding that can accept Secure Sockets Layer (SSL) connections.
You have a client certificate installed on the client.

Configure certificate mapping by Configuration Editor

Launch the IIS manager and select the web site to be configured for client certificate authentication.
In the Features View, select Configuration Editor under the Management section.
Go to system.webServer/security/authentication/iisClientCertificateMappingAuthentication in the drop-down box as shown in the following image:

You'll see a window to configure Many-to-One or One-to-One certificate mappings here. The following UI is provided through Configuration Editor from where you can set up all of the mapping configurations.
Modify the properties through this graphical user interface (GUI).
- Set enabled to True.
- Set manyToOneCertificateMappingsEnabled to True.
- Select manyToOneMappings and select on the ellipsis button to launch a new window for configuring mappings.
Under this new window, select to add a new item. You can modify the properties within the window as shown in the following image:
Select 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's the matchcriteria property to map the certificate to the account mydomain\testuser.

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

Screenshot of an item that has two entries for rules.

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

Configure certificate mapping by APPCMD.exe

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 the 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 it from inside the UI itself:

Select the Generate Script option to run commands.

Run commands manually in the Script Dialog window.

These code snippets perform the same steps to configure the certificate mapping. They were generated using Configuration Editor's Generate Script feature.

AppCmd commands

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();

Share via