IIS Client Certificate Mapping Authentication

7 min readJun 23, 2022

What is Authentication?

Authentication is the process of identifying and providing that identity to a remote service. It is the process of proving that you are who you say you are.

What is Client Certificate Mapping Authentication?

IIS provides six authentication options. One of these options is called “Client Certificate Authentication”. In this authentication option, the client presents a certificate to the server, the server configured to map certificates to one or more Windows user accounts

IIS supports three Client Certificate authentication mechanisms:

One-to-One Client Mapping => each individual trusted user certificate is mapped to a Windows user account.
Many-to-One Client Mapping => Multiple trusted user certificates are mapped to a single Windows user account.
Active Directory Mapping => Certificates are passed to Active Directory, which will validate if the mapping is correct.

Prerequisites:

Certificate

I have bought a domain “awesomedefaultwebsite.space” and created a certificate for it.

IIS and require module: IIS Client Certificate Mapping Authentication module

PS:

Install-WindowsFeature -name Web-Cert-Auth

There is no dedicated UI option for enabling and configuring One-to-One or Many-to-One Certificate mapping. We will have to use IIS Manager’s Configuration Editor.

First, we need to configure our site for client certificate authentication and define a cryptographic strength required for encrypting those certificates.

Open IIS Manager > Select your site/application > Configuration Editor > system.webServer/security/access > sslFlags

You will have the following options:

None =>This default setting disables SSL for the site or application.
Ssl => The site or application requires SSL.
SslNegotiateCert => The site or application accepts client certificates for authentication.
SslRequireCert => The site or application requires client certificates for authentication.
Ssl128 =>The site or application requires 128-bit SSL certificate encryption.

< I do want to make a distinction here; one thing is that your site uses SSL (HTTPS), and another thing is that your site uses a certificate as an authentication mechanism >

I selected “SSL”, “SslNegotiateCert” and “SslRequireCert”. This means the following:

I will only allow SSL connections to my site. There for, HTTP is not an option.
That my site can accept client certificates for authentication.
That my site requires a client certificate for authentication.

In doing so, this will modify the SSL Settings module in the following manner:

One-to-One Certificate Mapping

“

The <oneToOneMappings> element of the <iisClientCertificateMappingAuthentication> element maps individual client certificates to individual user accounts on a one-to-one basis.

“

Go to Configuration Editor > system.webServer/security/authentication/iisClientCertificateMappingAuthentication

Enabled: True.

This will enable Client Certificate Mapping Authentication.

Now we need to map a certificate to a user account.

Select “oneToOneMappings” > … > Add >

In here, it will ask you for the following:

certificate => Base-64 encoded string.
userName => account that will be the one used to log in.
password => password of that account

Now, if a client presents a valid certificate, it will enter the site as “azureuser” account.

How to get the Base-64 encoded string of your certificate.

Export your certificate as “Base-64 encoded X.509 (.CER)

Open the certificate in Notepad, and remove “Begin” and “End” lines.

Take the whole string and concatenate it. I just copy and paste it into the browser and then copied it again.

Now, just paste it into the certificate field in Configuration Editor.

Test it:

You will actually need respective HTTPS binding:

These are the possible valid certificates that I have at the moment:

Made a request to “https://awesomedefaultwebsite.space” and selected a certificate.

However, none of these certificates are correct. Therefore, the Server will say, “I know who you are, and you are not allowed”.

403.16 => Client certificate is untrusted or invalid.

I moved the .pfx certificate from the server to my laptop and import it here:

I made another request and chose the correct certificate, the one that we set the mapping for:

The IP address of my laptop is 200.202.XX.XX.

In the IIS Logs, we should be able to see that IP in “c-ip:” field and in “cs-username” we should see “azureuser”. This is the account that we chose to log in as.

2022–06–23 16:55:04 10.1.0.4 GET /iisstart.png — 443 azureuser 201.202.XX.XX Mozilla/5.0+(Windows+NT+10.0;+Win64;+x64)+AppleWebKit/537.36+(KHTML,+like+Gecko)+Chrome/102.0.5005.124+Safari/537.36+Edg/102.0.1245.44 https://awesomedefaultwebsite.space/ 200 0 0 564

Many-to-One Certificate Mapping

“The <manyToOneMappings> element of the <iisClientCertificateMappingAuthentication> element maps multiple client certificates to a user account based on criteria in the client's browser certificate.

“

Here, it is possible to match many certificates to a Windows User Account. Given that certificates have fields and subfields, it uses fields: Subject or Issuer to match the certificate.

For example, I can use “Issuer” field and “O” subfield, that if “O” matches “ZeroSSL”, then that certificate is valid and it will log in as the user I choose.

Go to “system.webServer/security/authentication/iisClientCertificateMappingAuthentication > manyToOneMappings>… > set following values”:

Again, “userName” and “password” will be for the account that will log in, if the certificate is valid.

Now go to “rules > …”

Select the Field that you want to use, sub field, and the matching Criteria.

I made a request, selected the certificate, and as “Issuer” field — “O” subfield matches “ZeroSSL”, it granted access and “test” account was used to log in:

In the IIS Logs, we do see “test” account, IP Address of my laptop and that is was a status code 200.

2022–06–23 17:13:09 10.1.0.4 GET / — 443 test 201.202.XX.XX Mozilla/5.0+(Windows+NT+10.0;+Win64;+x64)+AppleWebKit/537.36+(KHTML,+like+Gecko)+Chrome/102.0.5005.124+Safari/537.36+Edg/102.0.1245.44–200 0 0 583

Final Thoughts

Client Certificate Mapping Authentication is one of the options that IIS provides in order to authenticate.
You could encounter the following status codes: (See the documentation on how to troubleshoot it):

403.7 => Client certificate required. The site required a certificate and the client did not send it.

403.16 => Client certificate is untrusted or invalid. The client sent a certificate but the Site does not trust it.

403.17 => Client certificate has expired or is not yet valid.

Understand that, if client mapping authorization fails, it will go ahead and use the authentication that you have in the “Authentication module”. This behavior may change depending on what you have in sslFlags.
If you only have “SslNegotiateCert” and you do not have any valid certificate, the other Authentication protocol that you have will be used. In case you have potential valid certificate, it would ask you to choose a certificate, if you chose an incorrect certificate, it would give you 403.16. It will not use the other authentication option that you have in the “Authentication module”.

Thought this could be useful to somebody.