client authentication windows

Om op Windows gehoste systemen client certificaat validatie toe te kunnen passen zijn soms behoorlijk wat stappen nodig. Deze zijn helaas niet even goed terug te vinden waardoor de implementatie nog wel eens op vraagtekens stuit. Er zijn verschillende mogelijkheden om dit voor elkaar te krijgen. Het kan binnen de applicatiecode worden opgelost, echter kan het ook volledig door IIS zelf gedaan worden. Om ondersteuning te bieden voor de laatste case is er een referentie handleiding geschreven. Deze handleiding werkt voor de 'kale' setup van IIS. Het spreekt voor zich dat dit geen uitputtende handleiding is, daarvoor zijn de mogelijke implementatiescenario's te divers.

Deze handleiding is geschreven voor Windows 2012r2 (Engelse editie) met IIS 8.5. Het zou ook moeten werken op Windows 2012 met IIS 8. Op eerdere versies van IIS werkt het niet, daar werkt client certificate authentication fundamenteel anders.

De handleiding gaat uit van een server met een al werkende webservice met een https endpoint en zonder gebruikmaking van ServerName Indication.

Eindresultaat van de handleiding is:

De server accepteert alleen certificaten welke zijn uitgegeven onder de PKIoverheid Organisatie boom
De server geeft de client de Acceptable Client Certificates lijst terug (TLS handshake veld 'certificate_authorities')

Register

Sta het verzenden van de Acceptable Client Certificates lijst toe middels een register aanpassing. Start regedit en pas de volgende sleutel aan / voeg deze toe:

DWORD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\SendTrustedIssuerList met waarde 1

Let op! Pas op voor spaties in de sleutel naam.

Accepteer alleen client certificaten als deze uitgegeven zijn door een vertrouwde leverancier (PKIoverheid). Hiervoor wordt een specifieke trustlist gehanteerd die in de komende hoofdstukken wordt geïmplementeerd. Hiervoor moet de standaard instelling onder Windows 2012 ingesteld staan. Als de volgende sleutel ingesteld is moet deze worden verwijderd of op waarde 0 worden ingesteld:

DWORD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\ClientAuthTrustMode

Issuer certificaten importeren

Download de Organisatie certificaten van https://cert.pkioverheid.nl/. (Zoals uitgelegd verderop op de wiki)
Het is belangrijk om de certificaten te importeren naar de Local Machine in de import wizard
Selecteer in de import wizard een custom Certificate store: Client Authentication Issuers
Importeer de twee PKIoverheid Organisatie issuer certificaten van PKIoverheid naar deze certificate store: Staat der Nederlanden Organisatie CA - G2 en Staat der Nederlanden Services CA - G3

IIS configuratie

Open de IIS Manager en selecteer de website waar je de client certificate authentication aan wil toevoegen
Er wordt van uitgegaan dat er op deze website al een https binding actief is. Check voor de zekerheid dat is inderdaad het geval is alvorens je verder gaat
Open in IIS de websites SSL Settings en zet daar Require SSL aan en selecteer Require onder Client certificates. Pas de changes vervolgens toe
Start een nieuwe shell en typ:

netsh
http
show sslcert

Kopieer de Certificate Hash, Application ID en Certificate Store Name waarden. Deze zijn later weer nodig. Typ nu:

delete sslcert ipport=0.0.0.0:443

Let bij het volgende commando op de quotes!!

add sslcert ipport=0.0.0.0:443 certhash=<your hash> appid="<your app id>" sslctlstorename=ClientAuthIssuer certstorename=<your cert store> clientcertnegotiation=enable
show sslcert

Dit zou moeten resulteren in de volgende uitvoer:

IP:port                      : 0.0.0.0:443
Certificate Hash             : <your hash>
Application ID               : <your id>
Certificate Store Name       : <your cert store>
Verify Client Certificate Revocation : Enabled
Verify Revocation Using Cached Client Certificate Only : Disabled
Usage Check                  : Enabled
Revocation Freshness Time    : 0
URL Retrieval Timeout        : 0
Ctl Identifier               : (null)
Ctl Store Name               : ClientAuthIssuer
DS Mapper Usage              : Disabled
Negotiate Client Certificate : Enabled

Testen

Het resultaat van alle changes is te zien met de volgende commando's.

openssl s_client -connect <domain of your service>:443

Naast andere uitvoer, moet je in ieder geval terug zien komen:

Acceptable client certificate CA names
/C=NL/O=Staat der Nederlanden/CN=Staat der Nederlanden Organisatie Services CA - G3
/C=NL/O=Staat der Nederlanden/CN=Staat der Nederlanden Organisatie CA - G2

Op de server zelf kan je testen met een verzoek naar localhost in de browser (https://localhost). Het volgende zou teruggegeven moeten worden (na het accepteren van een certificaat waarschuwing omdat het server certificaat niet geldt voor localhost): HTTP Error 403.7 - Forbidden

Met een tool als cURL kan je checken of de client certificaat acceptatie werkt zoals verwacht:

curl -k -E /path/to/full/cert_bundle.pem https://<domain of your service>

De webpagina of de uitkomst van de webservice moet nu zijn zoals je die ook zou verwachten voordat je client certificaat authentication had aangezet. Als je nu hetzelfde request doet met een client certificaat van een niet door OSO geaccepteerde issuer of helemaal zonder client certificaat, dan moet je http error 403 (Access is denied) zien.

Als het nu niet werkt, dan is het belangrijk om te weten dat client certificate authentication internet toegang vereist voor de server. Het authentication proces in IIS vereist namelijk het downloaden van de issuers CRL (certificate revocation list). Wanneer je HTTP status 403 (substatus 13) in de IIS logs ziet voor elk request (met of zonder certificaat) dan kan de CRL niet gedownload worden. In dit geval moet je een uitgaande connectie toestaan in de firewall, of je moet een outbound http proxy instellen op de server.

Proxy

Als je een proxy gebruikt, moet je IIS instellen zodat deze de proxy ook gebruikt:

Als dit nog niet zo is, zet de proxy settings in Internet Explorer op de server
Hergebruik de netsh shell en typ de volgende regels:

winhttp

Check of er niet toch een proxy is ingesteld. Zo ja, check of dit wel correct en delete anders deze settings

show proxy
import proxy source=ie

Check of de nieuwe settings er in staan

show proxy

Probeer de certificate tests opnieuw

Issues

Mocht je nog steeds tegen issues aanlopen, check dan grondig de ingevulde waarden. Volg ook de volgorde van de opgegeven commando's zodat alle configuratie correct aan elkaar gelinkt is. Probeer in het uiterste geval een reboot van IIS en anders de gehele server.

NB. Verander nu niet meer de https bindings in de IIS GUI. Doe je dit wel dan verwijder je ook alle settings die je met netsh hebt gemaakt voor deze binding.

OSO:2018/beveiliging/client authentication windows