IIS 7.0 : Implementing Access Control – Authentication (part 3) – IIS Client Certificate Mapping Authentication

IIS Client Certificate Mapping Authentication

IIS Client Certificate Mapping Authentication enables clients to authenticate with the Web server by presenting client certificates over Secure Socket Layer (SSL) connections.

Note

Certificate-based authentication enables clients to use client certificates to authenticate with the Web server. It is not required to enable secure communication between the client and the server using SSL.

The IIS Client Certificate Mapping Authentication provides a more flexible mechanism for authenticating clients based on client certificates than does the Active Directory–based Client Certificate Mapping Authentication. Instead of relying on the Directory Services Mapper (DS Mapper) service to map client certificates to Windows accounts, it uses the configuration to perform the mapping. As such, it also does not require the user accounts to be domain accounts and does not require Active Directory to operate.

Note

IIS Client Certificate Mapping Authentication is not part of the default IIS install and is not enabled by default. You can manually install it from the Security feature category through Turn Windows Features On And Off on Windows Vista. You can also install it via the Security role service category of the Web Server (IIS) role in Server Manager on Windows Server 2008.

The IIS Client Certificate Mapping Authentication feature supports the following mapping types:

  • One-to-one mapping Map a single client certificate to a specific Windows account. The server will use an exact copy of the client certificate to perform the match and therefore must possess a copy of each client certificate.

  • Many-to-one mapping Map client certificates to a Windows account by matching wildcard expressions involving specific certificate fields, such as issuer or subject. This does not require a copy of the client certificate.

To use IIS Client Certificate Mapping Authentication, you need to meet the following requirements:

  • You cannot use Active Directory–based Client Certificate Mapping Authentication on any of the sites for which you enable IIS Client Certificate Mapping Authentication. 
  • You must have the passwords for all Windows accounts used to map certificates. Unlike Client Certificate Mapping Authentication, which relies on Active Directory to generate the Windows token for the account, you will need to specify both the user name and password for each account being mapped so that IIS can generate the token. 
  • To use one-to-one mappings, you must have an exact copy of each client certificate being mapped. If you provide the certificates to users, you will have this copy. Otherwise, you will need each user to provide you with an exported copy of the certificate. When using many-to-one mappings, you do not need copies of the certificates. 
Note

You do not need to use IIS Client Certificate Mapping Authentication to require clients to present client certificates. You can configure the server to always require client certificates to access the server and then use another authentication scheme to authenticate the client.

To enable IIS Client Certificate Mapping Authentication for a specific Web site or URL, you need to perform the following steps (after installing the IIS Certificate Mapping Authentication module):

1.

Enable IIS Client Certificate Mapping Authentication. This option is not available in IIS Manager. To do this, you will need to edit the system.webServer/security/authentication/iisClientCertificateMappingAuthentication section directly. Alternatively, you can use Appcmd or another configuration API. You can enable IIS Client Certificate Mapping Authentication with Appcmd by using the following syntax (see details on configuring this configuration section later in this section).

 

%systemroot%\system32\inetsrv\Appcmd set config [ConfigurationPath]
/section:system.webServer/security/authentication/
iisClientCertificateMappingAuthentication /enabled:true /commit:apphost

 

2.

Configure SSL on each Web site using this authentication method. Certificate authentication is possible only if the Web site is being accessed over an SSL connection. Therefore, it requires an SSL binding to be configured for the Web site.

 

3.

Configure each Web site using this authentication method to accept client certificates (and possibly require them). Doing so ensures that the server accepts client certificates when the clients provide them. Doing so can also configure the server to require the client to present a certificate to proceed with the request.

 

4.

Configure the required one-to-one or many-to-one mappings. Create the mappings to map certificates to Windows accounts.

 

Note

Although you can enable the IIS Client Certificate Mapping Authentication feature for a specific URL, the mapping configuration can only be set at the server or Web site level, and it is ignored if it is set at a lower configuration level.

Creating One-to-One Certificate Mappings

You can use one-to-one certificate mappings as part of a strong authentication and authorization scheme to control access to application resources based on the exact identity of the client. It can be used instead of a user name and password authentication scheme that requires the user to supply credentials. To use one-to-one mappings, you need to have the exact copy of each certificate.

IIS Manager does not provide support for configuring one-to-one mappings. You can configure them by using the Appcmd command line tool. You can also do it by editing the system.webServer/security/authentication/iisClientCertificateMappingAuthentication configuration section directly or with other configuration APIs. You can add a one-to-one mapping by using the following Appcmd syntax.

%systemroot%\system32\inetsrv\Appcmd set config [SiteName]
/section:system.webServer/security/authentication/
iisClientCertificateMappingAuthentication /+oneToOneMappings
[certificate='string',enabled='bool',username='string',password='string']
 

You can remove a one-to-one mapping by using the following Appcmd syntax.

%systemroot%\system32\inetsrv\Appcmd set config [SiteName]
/section:system.webServer/security/authentication
/iisClientCertificateMappingAuthentication /-oneToOneMappings
[certificate='string']
 

These commands use the parameters in Table 4.

Table 4. Parameters for Creating Certificate Mappings
ParameterDescription
SiteNameThe site name of the Web site for which to set these settings. If omitted, this parameter sets them for the entire Web server. If you specify these settings for a configuration path deeper than the Web site root, these settings will not take effect.
certificateThe exact text of the certificate (not the certificate hash).
enabledWhether or not this mapping is enabled.
userNameThe user name for the account to which the certificate maps.
passwordThe password for the account to which the certificate maps. This value is stored in the encrypted form.

You can obtain the exact text of the certificate from an exported certificate file (containing unencrypted certificate information) or by dumping the certificate from the local or domain certificate store. To do the latter, you can use the following command.

certuil –encode –f CertName cert.cer

CertName is the friendly name of the certificate. You can view the certificate store and obtain the friendly name of the installed certificates with the following command.

certuil –viewstore StoreName

StoreName is the name of the certificate store. Use MY for the personal certificate store.

Note

You must specify the exact base64 encoded certificate contents for the one-to-one mapping, with the training line feed removed. Do not use the certificate hash. If you do not specify the certificate correctly, you will get a 401.1 status error when making requests to the Web site. This error will show the 0x8009310b HRESULT, indicating that IIS failed to load the certificate from the mapping entry.

Creating Many-to-One Certificate Mappings

Many-to-one mappings, unlike one-to-one mappings, are not typically used to authenticate specific users. Instead, you can use them to authenticate a group of users by matching fields in their certificates to a single Windows account. Therefore, authorization based on the authenticated user produced by a many-to-one mapping is similar to role- or group-based authorization, with the authenticated user representing a group to which multiple users belong. For example, you can match all certificates issued by a specific organization to that organization’s account. As such, many-to-one mappings may be less appropriate for user-based personalization or access control than one-to-one mappings, depending on your authorization strategy.

Note

One-to-one mappings are always processed before many-to-one mappings.

 

Many-to-one mappings do not require the server to have the exact certificate for each user. Instead, you simply configure wildcard rules based on one or more fields in the certificate that map all certificates with matching fields to a Windows account.

IIS Manager does not provide support for configuring many-to-one mappings. You can configure them by using the Appcmd command line, too. You can also edit the system.webServer/security/authentication/iisClientCertificateMappingAuthentication configuration section directly or with other configuration APIs. You can add a one-to-one mapping by using the following Appcmd syntax.

%systemroot%\system32\inetsrv\Appcmd set config [SiteName]
/section:system.webServer/security/authentication/
iisClientCertificateMappingAuthentication /+manyToOneMappings
[name='string',enabled='bool',permissionMode='enum',
username='string',password='string',description='string']
 

Then, you have to add one more matching rule to the mapping by using the following Appcmd syntax, specifying the name of the mapping created in the command shown previously.

%systemroot%\system32\inetsrv\Appcmd set config [SiteName]
/section:system.webServer/security/authentication/
iisClientCertificateMappingAuthentication /+manyToOneMappings
[name='string'].rules.[certificateField='enum',
certificateSubField='string',matchCriteria='string',
compareCaseSensitive='bool']

You can delete a mapping by using the following Appcmd syntax.

%systemroot%\system32\inetsrv\Appcmd set config [SiteName]
/section:system.webServer/security/authentication/
iisClientCertificateMappingAuthentication /-manyToOneMappings
[name='string']
 

These commands use the parameters in Table 5.

Table 5. Parameters for Creating Certificate Mappings
ParameterDescription
SiteNameThe site name of the Web site for which to set these settings. If omitted, sets them for the entire Web server. If you specify these settings for a configuration path deeper than the Web site root, these settings will not take effect.
nameThe name of the mapping; can also be used to add rules to it or delete it.
enabledWhether or not this mapping is enabled.
permissionModeWhether to allow or deny access to the user who is given this mapping.
userNameThe user name for the account to which the certificate maps.
passwordThe password for the account to which the certificate maps. This value is stored in the encrypted form.
descriptionThe friendly description of the mapping.
certificateFieldThe certificate field to match in the current rule. Common fields are Issuer and Subject. For more information, get the details about the contents of the certificate from the CA.
certificateSubFieldThe certificate subfield to match in the current rule. For more information on the subfields, get the details about the contents of the certificate from the CA.
matchCriteriaThe match criteria. This can include * and ? wildcard matching characters.
compareCaseSensitiveWhether or not the comparison should be case-sensitive.