Configuring One-to-One Client Certificate Mappings

Article
05/14/2020

Background

IIS 6 had a User Interface to configure and map one to one certificates for authentication. It allowed users to select the validation client certificate and assign the authorized user credentials. There isn't a similar UI in IIS 7 and above. This walkthrough is designed to instruct users to configure one to one client certificates using Administration Pack's Configuration Editor. Users who do not have this add-on can view the appendix section for AppCmd arguments and C# code examples to perform this walkthrough.

IIS 7 and Above Schema

This is the schema for the IIS Client Certificate Mapping Authentication Feature in IIS 7 and above.

<sectionSchema name="system.webServer/security/authentication/iisClientCertificateMappingAuthentication">
  <attribute name="enabled" type="bool" defaultValue="false" />
  <attribute name="oneToOneCertificateMappingsEnabled" type="bool" defaultValue="true" />
  <element name="oneToOneMappings">
    <collection addElement="add" clearElement="clear">
      <attribute name="enabled" type="bool" defaultValue="true" />
      <attribute name="userName" type="string" />
      <attribute name="password" type="string" encrypted="true" />
      <attribute name="certificate" type="string" required="true" isUniqueKey="true" />
    </collection>
  </element>
</sectionSchema>

Prerequisites

These are the prerequisites needed for this walkthrough. I won't be covering how to create or do these things.

Installed IIS Client Certificate Mapping module
A Web Site with an HTTPS binding, properly configured
A Base-64 certificate (.cer file). [Note: This can be any valid 64-bit certificate, but it must be in file form]
Installed a client certificate on a client
Installation of IIS 7 Administration Pack Technical Preview 2

Step 1: Getting the Certificate Blob

The oneToOneMappings collection item has an attribute called certificate. The required value for this attribute is not the certificate has but the actual certificate blob. Here's how you extract it.

Right click on your .cer file.
Select Open With... in the context menu
Select Notepad from the list of Other Programs and click OK. [Note: Notepad may be hidden beneath a drop down in the Vista/Windows 2008 list view]

This is what should be displayed in notepad:

Remove -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----
Format the certificate blob to be a single line.
Save this file as clientCertBlob.txt

Step 2: Enabling IIS Client Certificates Mapping Authentication and One to One Certificate Mapping For A Web Site

The next steps will cover how to enable the Client Certificate Mapping Authentication feature, One to One Certificate Mapping and added a mapping entry.

Start Inetmgr, the IIS Manager UI
Select the SSL web site that is being configured and open Configuration Editor
Type "system.webServer/security/authentication/iisClientCertificateMappingAuthentication" in the Section drop down box.
Select the enabled field and change the value to true
Select the oneToOneCertificateMappingsEnabled property grid entry and change the value to true
Select the oneToOneMappings property grid entry and click Edit Items... in the Actions Task Pane
Click Add in the Collection Editor task list
Copy the single string certificate blob from above and paste it into the certificate field
Set the userName and password that clients will be authenticated as.
Set the enabled field to true
Close Collection Editor
Click Apply in the Actions Task Pane [Note: Click Script Generation prior to clicking Apply to get scripts for this process]

Once this is complete the server will be configured to handle IIS Client Certificate Mapping authentication with a single one to one certificate mapping entry.

Step 3: Enabling Client Certificate Authentication For A Web Site Using SSL

Once a mapping has been created and the feature has been enabled, a site must be configured to use client certificates.

From within Inetmgr, the IIS Manager UI, select the SSL web site you want to use client certificates
Select the SSL UI module
Under Client certificates: selectthe Accept radio button
Click Apply in the Actions Task Pane

Now the web site is configured to accept and authenticate clients based on client certificates.

Step 4: Verifying It All Works

The client that is trying to access the SSL web page needs the client certificate properly installed. If a client attempts to request a page without the certificate a 401 will be served. Once the client certificate is correctly installed, the page will be served as normal.

Play around with different combinations of authorization rules to suit your needs.

Summary

You have now configured IIS Client Certificate Mappings and a single One to One Certificate mapping.

Appendix

These are the Code Snippets to perform walkthrough steps 2 and 3. All of this was generated using Configuration Editor's Script Generation.

AppCmd specific instructions

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

appcmd.exe set config "Default Web Site" -section:system.webServer/security/authentication/iisClientCertificateMappingAuthentication 
    /+"oneToOneMappings.[userName='testUser',password='securePassWord!1',certificate='CERTIFICATE_BLOB']" /commit:apphost

appcmd.exe set config "Default Web Site" -section:system.webServer/security/access /sslFlags:"Ssl, SslNegotiateCert, Ssl128"  /commit:apphost

C# Code:

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["oneToOneCertificateMappingsEnabled"] = true;
            
            ConfigurationElementCollection oneToOneMappingsCollection = 
                     iisClientCertificateMappingAuthenticationSection.GetCollection("oneToOneMappings");
            
            ConfigurationElement addElement = oneToOneMappingsCollection.CreateElement("add");
            addElement["userName"] = @"testUser";
            addElement["password"] = @"securePassWord!1";
            addElement["certificate"] = @"CERTIFICATE_BLOB";
            oneToOneMappingsCollection.Add(addElement);
            
            serverManager.CommitChanges();
        }
    }
}

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 accessSection = config.GetSection("system.webServer/security/access", "Default Web Site");
            accessSection["sslFlags"] = @"Ssl, SslNegotiateCert, Ssl128";
            
            serverManager.CommitChanges();
        }
    }
}

Share via