Skip to content

Commit af961f4

Browse files
mmerklingermmerklinger
authored
Add TLS client authentication configuration for Windows IIS (#479)
1 parent dff80e7 commit af961f4

File tree

3 files changed

+204
-0
lines changed

3 files changed

+204
-0
lines changed

‎source/components/nitrokeys/features/piv/guides/index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,6 @@ Guides
88
:glob:
99

1010
client_logon_with_active_directory.rst
11+
tls-client-authentication-with-internet-information-services-and-active-directory.rst
12+
tls-client-authentication-with-internet-information-services.rst
13+

‎source/components/nitrokeys/features/piv/guides/tls-client-authentication-with-internet-information-services-and-active-directory.rst

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
TLS Client Authentication with Windows Internet Information Services (IIS) and Active Directory
2+
-----------------------------------------------------------------------------------------------
3+
4+
.. product-table:: nk3
5+
6+
This guide describes the configuration of Windows Internet Information Services (IIS) for TLS client authentication that maps users to Active Directory accounts.
7+
8+
It shows the configuration as an example with the *Default Web Site* of IIS.
9+
The configuration can also be used for other sites, including or excluding the default site, but the configuration of TLS support is server-wide.
10+
11+
Prerequisits
12+
============
13+
14+
- Successful setup of smart card client logon, refer to chapter `Client logon with Active Directory <client_logon_with_active_directory.html>`__.
15+
Users must have a valid authentication certificate on a Nitrokey.
16+
- Windows Server (web server)
17+
18+
- Joined to an Active Directory domain.
19+
- DNS record or hostname must be possible to resolve through DNS for the clients.
20+
- TLS certificate for the DNS record.
21+
Client computers must trust this TLS certificate.
22+
23+
Installation
24+
============
25+
26+
1. Open the *Server Manager*.
27+
2. In the menubar on the top click **Manage → Add Roles and Features**.
28+
3. Follow the wizard to the step **Server Roles**.
29+
4. Select the role **Web Server (IIS)** from the list of available roles.
30+
5. Follow the wizard to the step **Roles Services** under **Web Server Role (IIS)**.
31+
6. From the list of role services select **Web Server → Security → Client Certificate Mapping Authentication**.
32+
7. Follow the wizard to the installation.
33+
Installation must be finished before you can start configuring it.
34+
35+
Configuration
36+
=============
37+
38+
1. Open the *Internet Information Services (IIS) Manager* (``InetMgr.exe``).
39+
2. Select and expand the web server you want to configure in the **Connections** tree view on the left.
40+
3. From the middle pane open **Authentication**.
41+
Select **Active Directory Client Certificate Authentication** and enable it with a click on **Enable** in the **Actions** pane on the right.
42+
4. Expand the **Sites** under the web server and select the site you want to configure.
43+
5. In the **Actions** pane on the right click **Bindings...**.
44+
6. Click **Add...** which brings up the bindings editor.
45+
Set the type to **https** and the hostname according to the DNS record and the TLS certificate's Subject Alternative Name (SAN) attribute.
46+
Activate the checkbox **Disable TLS 1.3 over TCP**.
47+
In the field **SSL certificate** select the respective certificate.
48+
Confirm the configuration with a click on **OK**.
49+
50+
.. tip::
51+
To understand the requirement to disable TLS 1.3 and for a configuration instructions on how to use it with enabled TLS 1.3, refer to this `Microsoft Support blog post <https://techcommunity.microsoft.com/blog/iis-support-blog/windows-server-2022-iis-web-site-tls-1-3-does-not-work-with-client-certificate-a/4129738>`__.
52+
53+
7. From the middle pane open **SSL Settings**.
54+
Activate the checkbox **Require SSL** and the radio button under **Client certificates** is set to **Require**.
55+
Confirm the configuration with a click on **Apply** in the **Actions** pane on the right.
56+
8. From the middle pane open **Authentication**.
57+
Make sure that all other authentication methods are deactivated for the site.
58+
The *Active Directory Client Certificate Authentication* will be never visible in this list.
59+
60+
.. important::
61+
If any other type of authentication is enabled, the client certificate mapping won't work.
62+
63+
The site is now configured for TLS client authentication using Active Directory user account mapping.
64+

‎source/components/nitrokeys/features/piv/guides/tls-client-authentication-with-internet-information-services.rst

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
TLS Client Authentication with Internet Information Services (IIS)
2+
------------------------------------------------------------------
3+
4+
.. product-table:: nk3
5+
6+
This guide describes the configuration of Windows Internet Information Services (IIS) for TLS client authentication that maps users to local user accounts.
7+
8+
It shows the configuration as an example with the *Default Web Site* of IIS.
9+
The configuration can also be used for other sites, including or excluding the default site.
10+
11+
Prerequisits
12+
============
13+
14+
- Nitrokey 3 with PIV client authentication certificate.
15+
- Windows Server (web server)
16+
17+
- DNS record
18+
- TLS certificate for the DNS record.
19+
Client computers must trust this TLS certificate.
20+
21+
Installation
22+
============
23+
24+
1. Open the *Server Manager*.
25+
2. In the menubar on the top click **Manage → Add Roles and Features**.
26+
3. Follow the wizard to the step **Server Roles**.
27+
4. Select the role **Web Server (IIS)** from the list of available roles.
28+
5. Follow the wizard to the step **Roles Services** under **Web Server Role (IIS)**.
29+
6. From the list of role services select **Web Server → Security → IIS Client Certificate Mapping Authentication**.
30+
7. Follow the wizard to the installation.
31+
Installation must be finished before you can start configuring it.
32+
33+
Configuration
34+
=============
35+
36+
1. Open the *Internet Information Services (IIS) Manager* (``InetMgr.exe``).
37+
2. Select and expand the web server you want to configure in the **Connections** tree view on the left.
38+
3. From the middle pane open **Configuration Editor**.
39+
Open the section ``system.webServer/security/authentication/iisClientCertificateMappingAuthentication`` and unlock it with a click on **Unlock Section** in the **Actions** pane on the right.
40+
4. Expand the **Sites** under the web server and select the site you want to configure.
41+
5. In the **Actions** pane on the right click **Bindings...**.
42+
6. Click **Add...** which brings up the bindings editor.
43+
Set the type to **https** and the hostname according to the DNS record and the TLS certificate's Subject Alternative Name (SAN) attribute.
44+
Activate the checkbox **Disable TLS 1.3 over TCP**.
45+
In the field **SSL certificate** select the respective certificate.
46+
Confirm the configuration with a click on **OK**.
47+
48+
.. tip::
49+
To understand the requirement to disable TLS 1.3 and for a configuration instructions on how to use it with enabled TLS 1.3, refer to this `Microsoft Support blog post <https://techcommunity.microsoft.com/blog/iis-support-blog/windows-server-2022-iis-web-site-tls-1-3-does-not-work-with-client-certificate-a/4129738>`__.
50+
51+
7. From the middle pane open **SSL Settings**.
52+
Activate the checkbox **Require SSL** and the radio button under **Client certificates** is set to **Require**.
53+
Confirm the configuration with a click on **Apply** in the **Actions** pane on the right.
54+
8. From the middle pane open **Authentication**.
55+
Make sure that all other authentication methods are deactivated for the site.
56+
The **IIS Client Certificate Mapping Authentication** will be never visible in this list.
57+
Navigate back to the root of the site.
58+
59+
.. important::
60+
If any other type of authentication is enabled, the client certificate mapping will not work.
61+
62+
9. From the middle pane open **Configuration Editor**.
63+
Open the section ``system.webServer/security/authentication/iisClientCertificateMappingAuthentication`` from ``ApplicationHost.config <location path='Default web site'/>``.
64+
Set the key ``enabled`` to ``True`` and make sure that one or both of the keys ``manyToOneCertificateMappingsEnabled`` and ``oneToOneCertificateMappingsEnabled`` are enabled.
65+
10. The user mappings must be written to the keys ``manyToOneMappings`` or ``oneToOneMappings``.
66+
The respective key to use depends on desired mapping to be used.
67+
You can find information about the mapping and more detailed configuration explanations on `Microsoft Learn <https://learn.microsoft.com/en-us/iis/configuration/system.webserver/security/authentication/iisclientcertificatemappingauthentication/>`__.
68+
69+
To change a key, click on the **...** button at the end of the value text field.
70+
This will open the *Collection Editor*.
71+
For creating a new mapping click on **Add** in the **Actions** pane on the right.
72+
73+
A. **Many to One mapping**
74+
75+
Fill in the fields as shown in the table below.
76+
77+
+--------------------+-------------------------------+
78+
| Key | Value |
79+
+====================+===============================+
80+
| ``enabled`` | ``True`` |
81+
+--------------------+-------------------------------+
82+
| ``name`` | ``<name-for-the-collection>`` |
83+
+--------------------+-------------------------------+
84+
| ``password`` | ``<user-password>`` |
85+
+--------------------+-------------------------------+
86+
| ``permissionMode`` | ``Allow`` |
87+
+--------------------+-------------------------------+
88+
| ``userName`` | ``<username>`` |
89+
+--------------------+-------------------------------+
90+
91+
The ``name`` field is used as an identifier of the collection and the ``userName`` and ``password`` require the username and password of the local user you want to map to.
92+
The ``rules`` field must contain the description of allowed or denied certificates.
93+
To change the rules key, click on the **...** button at the end of the value text field.
94+
This will open a new window of the *Collection Editor*.
95+
For creating new rule, click on **Add** in the **Actions** pane on the right.
96+
97+
Fill in the fields as shown in the table below.
98+
99+
+--------------------------+--------------------------------------------------------+
100+
| Key | Value |
101+
+==========================+========================================================+
102+
| ``certificateField`` | ``Subject`` |
103+
+--------------------------+--------------------------------------------------------+
104+
| ``certificateSubField`` | ``O`` |
105+
+--------------------------+--------------------------------------------------------+
106+
| ``compareCaseSensitive`` | ``True`` |
107+
+--------------------------+--------------------------------------------------------+
108+
| ``matchCriteria`` | ``<criteria-value-of-o-field-in-certificate-subject>`` |
109+
+--------------------------+--------------------------------------------------------+
110+
111+
Close the *Collection Editor* windows.
112+
113+
B. **One to One mapping**
114+
115+
Fill in the fields as in the tablebelow.
116+
117+
+-----------------+----------------------------------+
118+
| Key | Value |
119+
+=================+==================================+
120+
| ``certificate`` | ``<base64-encoded-certificate>`` |
121+
+-----------------+----------------------------------+
122+
| ``enabled`` | ``True`` |
123+
+-----------------+----------------------------------+
124+
| ``password`` | ``<user-password>`` |
125+
+-----------------+----------------------------------+
126+
| ``userName`` | ``<username>`` |
127+
+-----------------+----------------------------------+
128+
129+
The Base64 encoded certificate for the ``certificate`` field can be obtained from the Nitrokey with `Nitropy <../../../../software/nitropy/index.html>`__ and the command ``nitropy nk3 piv --experimental read-certificate --format PEM --key 9A``.
130+
The fields ``userName`` and ``password`` require the username and password of the local user you want to map to.
131+
132+
Close the *Collection Editor* window.
133+
134+
Confirm the configuration with a click on **Apply** in the **Actions** pane on the right.
135+
136+
The site is now configured for TLS client authentication using local user account mapping.
137+

0 commit comments

Comments
 (0)