Microsoft KB Archive/203805

= How to Map a Client Certificate to a Windows NT User Account =

Article ID: 203805

Article Last Modified on 6/22/2005

-

APPLIES TO


 * Microsoft Internet Information Server 4.0

-



This article was previously published under Q203805



We strongly recommend that all users upgrade to Microsoft Internet Information Services (IIS) version 6.0 running on Microsoft Windows Server 2003. IIS 6.0 significantly increases Web infrastructure security. For more information about IIS security-related topics, visit the following Microsoft Web site:

http://www.microsoft.com/technet/security/prodtech/IIS.mspx



SUMMARY
This article explains how to map a client certificate to a Windows NT user account. When this is done, the resources available to the client browsing the Web site are determined by that user account's permissions in the Access Control Lists (ACLs).



MORE INFORMATION
To map a client certificate to a user account, IIS must have access to a file that contains the ASCII text of that certificate. Because this is not typically available to the IIS computer, ASP is used to retrieve that information from the certificate, and then save it to a file on the server.

The Obtaining Client Certificate Information with ASP topic in the Windows NT Option Pack product documentation explains how to do this. However, a limitation of that code is that it creates the same file for all certificates.

To address this, the ASP code provided in this article creates a separate file for each certificate so that a file corresponding to each client is available for IIS to map to a user account.

NOTE: This ASP code appends the certificate's information to the text file every time the certificate is used to browse the ASP file. Because of this, you may want to take steps so that this information is only obtained once. Otherwise, the text file will grow in size indefinitely. To do this, use one of the following methods:
 * Instruct the clients to only browse to the ASP file one time, in order to "initialize" their mappings. Afterward, they should browse directly to the other files used in that Web site or directory, bypassing the ASP file that creates the text file. -or-


 * Add code to the ASP file to detect if a text file has already been created for the certificate.

NOTE: Because they use the Secure Sockets Layer (SSL), which encrypts and decrypts all data transmitted, pages that require certificates (which use the secure HTTPS protocol) load slower than pages that use the unsecured HTTP protocol.

  Create an ASP file, which the client will initially browse to in order to provide the client information that will be mapped to a user account. In the ASP file, add the following code above the  tag: <% @Language = VBScript %> <% 'Response.Buffer = True %>   Next, add the following code between the  and tags.

NOTE: In the "Set outStream = fs.OpenTextFile…" line, change the file path to the directory that will contain the text files on your server. <% 'Obtain client name cname = Request.ClientCertificate("SubjectCN")

'Instantiate the ASP FileSystemObject in order to create a text file Set fs = Server.CreateObject("Scripting.FileSystemObject")

'Create text file using append mode. The client name is used to create the file name. Set outStream = fs.OpenTextFile( "c:\InetPub\wwwroot\ClientFiles\" & cname &".txt", 8, True )

'Save certificate issuer information to text file outStream.WriteLine( "# Issuer: " & Request.ClientCertificate("Issuer") )

'Extract certificate subject (user) and account information 'from certificate su = Request.ClientCertificate( "Subject" ) mx = len(su) for x = 1 to mx if mid(su,x,1)=chr(10) or mid(su,x,1)=chr(13) then su=left(su,x-1)+";"+right(su,mx-x) end if        next outStream.WriteLine( "# Subject: " & su ) outStream.WriteLine( "# Account: " & Request.ServerVariables("REMOTE_USER"))

'Extract encrypted certificate text from certificate; encode text as 64-bit data uue = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" outStream.WriteLine( "-BEGIN CERTIFICATE-" ) cer = Request.ClientCertificate( "Certificate" ) lcer = len(cer) l = 0 for x = 1 to lcer step 3 a1 = asc(mid(cer,x,1)) if x+1 <= lcer then a2 = asc(mid(cer,x+1,1)) if x+2 <=lcer then a3 = asc(mid(cer,x+2,1)) else a3 = 0 end if               else a2 = 0 a3 = 0 end if   outStream.Write mid(uue, (a1 and 252)/4 +1 ,1) outStream.Write mid(uue, (a1 and 3)*16 + (a2 and 240)/16 +1 ,1) if x+1 <= lcer then outStream.Write mid(uue, (a2 and 15)*4 + (a3 and 192)/64 +1 ,1) if x+2 <= lcer then outStream.Write mid(uue, (a3 and 63) +1 ,1) else outStream.Write "=" end if               else outStream.Write "==" end if               l = l +4 if l = 64 then outStream.WriteLine("") l = 0 end if next

if l > 0 then outStream.WriteLine( "" ) end if        outStream.WriteLine( "-END CERTIFICATE-" ) Response.Write "Client certificate information has been received and logged successfully " %>                        Save the ASP file to the Web site or directory. Start the Internet Service Manager (ISM), which loads the Internet Information Server snap-in for the Microsoft Management Console (MMC). Right-click the Web site or directory that will contain the client text files, and then click Properties.</li> On the Directory (or Home Directory) tab, make sure that Write access permission is selected. This will allow the ASP file to create the text files in that directory. Click OK to return to the MMC.</li> Create and install a server certificate and key pair on the IIS computer.

NOTE: For information on how to do this using Microsoft Certificate Server, see the following article in the Microsoft Knowledge Base:

218445 How to Configure Certificate Server for Use with SSL on IIS

</li> In the MMC, right-click the Web site or directory where you will use client certificate mapping, and then click Properties. Click the Directory Security tab.</li> In the Secure Communications section, click the Edit button.</li> In the Secure Communications dialog box, select the Require Secure Channel when accessing this resource check box, and then select the Require Client Certificates option.</li> Have a client obtain a client certificate from the same Certificate Authority (CA) that issued the server's certificate.

NOTE: For information on how to do this using Certificate Server, see the following article in the Microsoft Knowledge Base:

218445 How to Configure Certificate Server for Use with SSL on IIS

</li> Have the client browse to the ASP file (that you created previously to obtain client certificate information) using the HTTPS protocol. After the client has successfully browsed to the ASP file using the client certificate, a corresponding text file will be created on the server.</li> Select the Enable Client Certificate Mapping check box, and then click the Edit button.</li> In the MMC, right-click the Web site or directory again, and then click Properties. Click the Directory Security tab.</li> In the Secure Communications section, click the Edit button.</li> In the Secure Communications dialog box, select the Enable Client Certificate Mapping check box, and then click the Edit button.</li> On the Basic tab, click the Add button. Select the text file created for that client certificate, and then click the Open button.</li> Type a descriptive Map Name, select the Windows NT user account that the client certificate should be mapped to, and then provide the user account's password. Click OK until you return to the MMC.</li></ol>

The next time the client browses to a file on this Web site or directory that requires a client certificate (using HTTPS), it will be logged on with the user account mapped to that client certificate.

Additional References
For more information please see the following topics in the product documentation:
 * Creating and Managing Server Key Pairs
 * Obtaining a Server Certificate
 * Enabling Client Certificates
 * Mapping Client Certificates to User Accounts
 * Obtaining Client Certificate Information with ASP

For additional information, see the following article or articles in the Microsoft Knowledge Base:

218445 How to Configure Certificate Server for Use with SSL on IIS

(c) Microsoft Corporation 2000, All Rights Reserved. Contributions by Kevin Zollman, Microsoft Corporation.

Additional query words: certsrv user name username wkz

Keywords: kbhowto KB203805

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.