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
| Parameter | Description |
|---|
| SiteName | The
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. |
| certificate | The exact text of the certificate (not the certificate hash). |
| enabled | Whether or not this mapping is enabled. |
| userName | The user name for the account to which the certificate maps. |
| password | The 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
| Parameter | Description |
|---|
| SiteName | The
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. |
| name | The name of the mapping; can also be used to add rules to it or delete it. |
| enabled | Whether or not this mapping is enabled. |
| permissionMode | Whether to allow or deny access to the user who is given this mapping. |
| userName | The user name for the account to which the certificate maps. |
| password | The password for the account to which the certificate maps. This value is stored in the encrypted form. |
| description | The friendly description of the mapping. |
| certificateField | The
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. |
| certificateSubField | The
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. |
| matchCriteria | The match criteria. This can include * and ? wildcard matching characters. |
| compareCaseSensitive | Whether or not the comparison should be case-sensitive. |
