IIS 7 Walkthrough: One to One Client Certificate Mapping Configuration

Posted: May 23, 2008  19 comments  

Average Rating

Share this Post

Note:  This blog post is now an article in the Learn section of IIS.NET.  http://learn.iis.net/page.aspx/478/configuring-one-to-one-client-certificate-mappings/

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.  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 Schema:

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

<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.

  1. Installed IIS Client Certificate Mapping module
  2. A Web Site with an HTTPS binding, properly configured
  3. A Base-64 certificate (.cer file).  [Note: This can be any valid 64-bit certificate, but it must be in file form]
  4. Installed a client certificate on a client
  5. 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.

  1. Right click on your .cer file.
  2. Select Open With...  in the context menu
  3. 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]
  4. This is what should be displayed in notepad:

    -----BEGIN CERTIFICATE-----
    MIIEfjCCA2agAwIBAgIKFW1IXAAAAAAAAjANBgkqhkiG9w0BAQUFADAbMRkwFwYD
    VQQDExBJSVNSZW1vdGVNZ3JUZXN0MB4XDTA4MDIxMTIxNTk1NloXDTA5MDIxMTIy
    MDk1NlowaDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNV
    BAcTB1JlZG1vbmQxDTALBgNVBAoTBE1TRlQxDDAKBgNVBAsTA0lJUzEVMBMGA1UE
    AxMMUkxVQ0VSTzItSUlTMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC3611j
    34q2qQgHa7ao11TcQMDYlJMrqET05MWFY1/Vso+leujLoIGTfdHOuz4IBVoeUE+y
    mlL8r53s2BQeVFROnDtg4Jko1zJsz7AUAnQNBk/GYA1AHYmhY79Z0p1KXW/wSTJB
    tdUn732GQOqYf4wY8jOD2zUJDUG4HXm6ib8ajwIDAQABo4IB+TCCAfUwDgYDVR0P
    AQH/BAQDAgTwMBMGA1UdJQQMMAoGCCsGAQUFBwMBMHgGCSqGSIb3DQEJDwRrMGkw
    DgYIKoZIhvcNAwICAgCAMA4GCCqGSIb3DQMEAgIAgDALBglghkgBZQMEASowCwYJ
    YIZIAWUDBAEtMAsGCWCGSAFlAwQBAjALBglghkgBZQMEAQUwBwYFKw4DAgcwCgYI
    KoZIhvcNAwcwHQYDVR0OBBYEFHbHA+HwZcIrslklj1W3O23UFrBgMB8GA1UdIwQY
    MBaAFMxzlGbmkp2+phhDg7TPfi83d7UVMHMGA1UdHwRsMGowaKBmoGSGL2h0dHA6
    Ly9paXNzYjMwNS9DZXJ0RW5yb2xsL0lJU1JlbW90ZU1nclRlc3QuY3JshjFmaWxl
    Oi8vXFxpaXNzYjMwNVxDZXJ0RW5yb2xsXElJU1JlbW90ZU1nclRlc3QuY3JsMIGe
    BggrBgEFBQcBAQSBkTCBjjBEBggrBgEFBQcwAoY4aHR0cDovL2lpc3NiMzA1L0Nl
    cnRFbnJvbGwvaWlzc2IzMDVfSUlTUmVtb3RlTWdyVGVzdC5jcnQwRgYIKwYBBQUH
    MAKGOmZpbGU6Ly9cXGlpc3NiMzA1XENlcnRFbnJvbGxcaWlzc2IzMDVfSUlTUmVt
    b3RlTWdyVGVzdC5jcnQwDQYJKoZIhvcNAQEFBQADggEBAEsSkcx0re36IL80UphJ
    w/srR3LBsy8sfwqxBMzMTdF7k6jYtUVpn3D2Dd4JXXVOaEVud9YNn9pr6xJL4t79
    Zh+hJzIPA5pQLbccx4vjWB4cWEYxzcoKYCuUdZrfPFXO1a5kQAj8IZ0/6bhMceyR
    Z7dRDoaIuAGQLFAlC/KjIBCemDi54MlWtvATQ8bmiRuEOWeneK2Vd2e0fxyezk05
    dRqa8DEC74CQN4rQuz395ECm+M/hQnN+dHOygV8n9swd0bdNq8qypwfVUes5HIpj
    LFmKTuGyFSVj7jv+64oTxvxtYX2QFp9q6Bi+qj0uyrX8Xjxy5rPSVPEfnxPCBg58
    RCI=
    -----END CERTIFICATE-----

  5. Remove -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----
  6. Format the certificate blob to be a single line.
  7. 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.

  1. Start Inetmgr, the IIS 7 Manager UI
  2. Select the SSL web site that is being configured and open Configuration Editor
  3. Type "system.webServer/security/authentication/iisClientCertificateMappingAuthentication" in the Section drop down box.
  4. Select the enabled field and change the value to true
  5. Select the oneToOneCertificateMappingsEnabled property grid entry and change the value to true
  6. Select the oneToOneMaapings property grid entry and click Edit Items... in the Actions Task Pane
  7. Click Add in the Collection Editor task list
  8. Copy the single string certificate blob from above and paste it into the certificate field
  9. Set the userName and password that clients will be authenticated as.
  10. Set the enabled field to true
  11. Close Collection Editor
  12. 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.

  1. From within Inetmgr, the IIS 7 Manager UI, select the SSL web site you want to use client certificates
  2. Select the SSL UI module
  3. Under Client certificates: select the Accept radio button
  4. 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();
        }
    }
}

Comments

great to see us finally document this!  Can you also make sure we post it as an article to learn.iis.net?

thanks!

May 23 2008 by bills

Ye great you have finally documented this !!! Come on MS is a big company just add the UI it is about time. If i wanted to edit conf files and use console i will use *nix, don't you get it ? Stop trying to make Windows more Linuxish, people prefer Windows not only because of the support / what support ? / but because there is / actually was / a nice GUI environment. It is not so much work to automate the process in a separate UI module, come on guys after all that is your job, and what kind of satisfaction do you get when your job is not properly done and the whole product is a mess.

Jun 22 2008 by Anonymous

To comment on the anonymous comment above:

Not all of our config sections and components warrent a UI.  This is one of the reasons why we have released Configuration Editor, which allows users who prefer the UI to edit config features that are not exposed through their own UI module.

The information above does not involve directly editing any of the IIS configuration files directly, but rather through tools that will interact with the config system in a productive manner.

Sep 10 2008 by rlucero

Comment to the Article: where should the file clientCertBlob.txt be saved. In the root of the page or the web root?

Comment to IIS 7.0: no GUI and no direct access of the IIS client certificate mapper to .cer files? These files must be manually converted to text!? What is going on here? Is this really the Windows Server product I have loved to use?

Nov 11 2008 by Anonymous

clientCertBlob.txt doesn't have to be saved.  The only thing that matters is the cert blob text with in it and that is unique to the certificate.  Saving it as a single line just makes it easier to access later if you want it.

Nov 24 2008 by rlucero

The entire text in clientCertBlob.txt needs to be pasted in the certificate parameter?

Jan 08 2009 by Anonymous

You don't need the ---BeginCertificate---- or the ---EndCertificate---- just everything in between.

Jan 08 2009 by rlucero

Hello,

I followed this walkthrough, and everythign seems fine, except one issue - when trying to log-in, after picking the certificate, IE still prompts me for user/password. What could be the problem?

Mar 10 2009 by Anonymous

Hi,

I followed this and all is good. I only have one issue - the user's passwords are in clear text. How do I set this up to encrypt the passwords?

Thanks.

Mar 10 2009 by Anonymous

i have followed all the steps what ever mentioned above but some problem as below,

i have configured a WCF Service to IIS and a  client  certificate is mapped.  and also under Turn Windows Features on or off.  IIS Client Certificate Mapping Authentication, checked.

The client able to access the wcf service at the same time other clients whose certificate is not configured still able to acess the wcf service.

to stop i have disabled the Anonymous Authentication then any client able to access now.

Could you please help me to how should i ensure that only configured client certifitcate only can access my WCF service

Thanks in Advance any help will appreciate.

Chandra

Dec 08 2011 by ChandraGupta

After disabling the Anonymous Authentication none of  the client able to access now.

even  i am not able to browse even in my system itself...

Dec 08 2011 by ChandraGupta

not sure why the above questions are still unanswered!!

Jun 07 2012 by nirman.doshi

I haven't had a chance to review all the questions recently.  I'll try to get back to people :)

Jun 07 2012 by rlucero

I have had IIS6 121 cert mappings running 100% for 2 years and migrating to IIS7. Now I try to follow these instructions, and still I receive "401.2 you are not authorized to view this page to invalid authentication headers" (using IE8 + imported client PFX). It works on IIS6. Please can somebody clarify what is extra is needed over and above the excellent directions given here using Configutation Editor. This is NOT working for me, and something is missing. As in IIS6, I have set site SSL to Require client certs + 121 maps + disabled all authentication modes (including Anonymous).

Jul 04 2012 by Anonymous

I am also having difficulty after disabling the Anon. Auth.

Aug 15 2012 by teapejon

Submit a Comment

  • Plain text is accepted.
  • URLs starting with http:// are converted to links.