Autentizace klientským certifikátem

Autentizace klientským certifikátem znamená, že se volající neprokazuje jménem, heslem ani tokenem, ale certifikátem uloženým ve svém úložišti. Ověření provede webový server IIS ještě dřív, než se požadavek dostane do aplikace — kód API se tedy spustí až u volání, které certifikátem prošlo.

Používá se u API vystaveného do internetu tam, kde druhá strana trvá na certifikátu místo tokenu — typicky banky, státní instituce a velcí zákazníci s vlastní certifikační autoritou. Celý postup ale platí pro libovolnou webovou aplikaci provozovanou na IIS, tedy i pro samotné NET Genium.

Certifikát a token se nevylučují. Certifikát ověřuje zařízení nebo systém, který se připojuje, a řeší ho IIS; token ověřuje konkrétního klienta a řeší ho kód aplikace — detailní popis tokenů je uveden v samostatné příručce API. Obě vrstvy se běžně kombinují: certifikátem se prokáže server druhé strany, tokenem pak konkrétní integrace.

1. Jak ověření probíhá

1. Klient naváže spojení HTTPS a server mu v rámci úvodní výměny pošle seznam certifikačních autorit, kterým důvěřuje.
2. Klient vybere certifikát vydaný některou z nich — prohlížeč zobrazí dialog pro výběr certifikátu, aplikace si certifikát bere z konfigurace — a prokáže se příslušným privátním klíčem.
3. IIS ověří platnost certifikátu a sestaví řetězec až ke kořenové autoritě. Ta musí být na serveru v úložišti „Trusted Root Certification Authorities“ („Důvěryhodné kořenové certifikační autority“), jinak ověření selže.
4. Podle nastavení IIS se s ověřeným certifikátem naloží jedním ze dvou způsobů:

Varianta	Co se nastavuje	Kdy ji zvolit
Mapování na uživatelský účet Windows	Role IIS a mapování v konfiguraci webu; aplikace se nemění	Požadavek má běžet pod konkrétním účtem Windows, nebo aplikace nemá být kvůli autentizaci upravována
Ověření certifikátu v kódu aplikace	Nastavení IIS a několik řádků kódu	Aplikace si má sama rozhodnout, komu certifikát patří, a podle toho odpovědět (typicky API)

Pro zprovoznění jsou zapotřebí:

• certifikáty — od protistrany, nebo vlastní testovací (viz následující kapitola),
• role IIS „IIS Client Certificate Mapping Authentication“ (pouze u mapování na účet Windows),
• konzole „MMC“ pro instalaci certifikátů,
• PowerShell spuštěný jako správce.

2. Certifikáty

V celém postupu vystupují tři certifikáty v různých rolích:

Certifikát	Kde je uložený	K čemu slouží
Kořenový (certifikační autorita)	Na serveru v úložišti „Trusted Root Certification Authorities“ počítače	Server podle něj ověřuje, že klientský certifikát vydala autorita, které důvěřuje
Serverový	Na serveru v úložišti „Personal“ počítače	Certifikát SSL nastavený v bindingu webu (HTTPS)
Klientský	Na klientském počítači v úložišti „Personal“ uživatele (u služby účtu, pod kterým služba běží)	Klient se jím prokazuje serveru

V produkčním nasazení předá klientský certifikát protistrana, nebo se pořizuje od veřejné certifikační autority. Kořenový certifikát bývá součástí předaného souboru; není-li, je nutné si ho vyžádat zvlášť a na serveru nainstalovat — bez něj nelze ověřit řetězec.

2.1. Vytvoření testovacích certifikátů

Pro vývoj a testování si lze certifikáty vygenerovat sám (takzvané self-signed certifikáty). Slouží k vyzkoušení celého řetězce; do produkce nepatří, protože jejich kořenovou autoritu nikdo kromě vašeho serveru nezná.

Certifikáty se generují příkazem „New-SelfSignedCertificate“ v PowerShellu spuštěném jako správce. Postup se skládá ze tří kroků: nejdřív vznikne kořenová autorita, tou se pak podepíše serverový i klientský certifikát.

# 1) Kořenová certifikační autorita
$ca = New-SelfSignedCertificate `
    -Type Custom `
    -Subject "CN=Priklad Test CA" `
    -KeyUsage CertSign, CRLSign, DigitalSignature `
    -KeyLength 4096 `
    -HashAlgorithm SHA256 `
    -KeyExportPolicy Exportable `
    -CertStoreLocation Cert:\LocalMachine\My `
    -NotAfter (Get-Date).AddYears(10) `
    -TextExtension @("2.5.29.19={text}CA=true")

# 2) Serverový certifikát podepsaný toutéž autoritou
$server = New-SelfSignedCertificate `
    -Type SSLServerAuthentication `
    -Subject "CN=api.priklad.cz" `
    -DnsName "api.priklad.cz" `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -KeyExportPolicy Exportable `
    -CertStoreLocation Cert:\LocalMachine\My `
    -Signer $ca `
    -NotAfter (Get-Date).AddYears(2)

# 3) Klientský certifikát podepsaný toutéž autoritou
$client = New-SelfSignedCertificate `
    -Type Custom `
    -Subject "CN=Klient XY" `
    -KeyUsage DigitalSignature, KeyEncipherment `
    -KeyLength 2048 `
    -HashAlgorithm SHA256 `
    -KeyExportPolicy Exportable `
    -CertStoreLocation Cert:\LocalMachine\My `
    -Signer $ca `
    -NotAfter (Get-Date).AddYears(2) `
    -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.2")

• Parametr „-DnsName“ u serverového certifikátu zapíše doménu do rozšíření „Subject Alternative Name“. Bez něj certifikát dnešní prohlížeče odmítnou — samotné „CN“ už jako název serveru neuznávají. Uvádí se všechny adresy, na kterých web poběží (parametr přijímá i více hodnot oddělených čárkou).
• Rozšíření „2.5.29.37“ u klientského certifikátu je „Extended Key Usage“ a hodnota „1.3.6.1.5.5.7.3.2“ znamená „Client Authentication“ (ověření klienta) — tedy použití, kvůli kterému certifikát vzniká.
• Kořenová autorita se vytváří bez rozšíření „Extended Key Usage“, aby jí bylo možné podepsat certifikát pro libovolné použití.

Vytvořené certifikáty se pak vyexportují do souborů — kořenový a klientský veřejný klíč (přípona „cer“) a klientský certifikát včetně privátního klíče (přípona „pfx“, chráněná heslem):

$heslo = Read-Host -AsSecureString -Prompt "Heslo k souboru PFX"

Export-Certificate    -Cert $ca     -FilePath C:\cert\CARoot.cer
Export-Certificate    -Cert $client -FilePath C:\cert\ClientCert.cer
Export-PfxCertificate -Cert $client -FilePath C:\cert\ClientCert.pfx -Password $heslo

Starší postupy používaly k témuž programy „makecert.exe“ a „pvk2pfx.exe“. Ty jsou dlouhodobě zrušené, součástí dnešních Windows nejsou a neumějí zapsat rozšíření „Subject Alternative Name“ — nepoužívejte je.

2.2. Instalace certifikátů na server

1. Spusťte konzoli „MMC“ (stačí zadat „mmc“ do vyhledávání) jako správce.
2. V nabídce „File“ zvolte „Add/Remove Snap-in…“ (Ctrl+M), vyberte „Certificates“ a tlačítkem „Add“ ho přidejte.
3. Zvolte „Computer account“, „Local computer“ a potvrďte tlačítkem „Finish“ a „OK“ — certifikáty serveru patří vždy do úložiště počítače, ne přihlášeného uživatele.
4. Klikněte pravým tlačítkem na složku „Trusted Root Certification Authorities“, zvolte „All Tasks / Import…“ a naimportujte kořenový certifikát (například „CARoot.cer“).
5. Týmž způsobem naimportujte do složky „Personal“ serverový certifikát včetně privátního klíče (například „ServerCert.pfx“).

Generovaly-li se certifikáty přímo na tomto serveru příkazem z předchozí kapitoly, jsou už v úložišti „Personal“ počítače — importuje se tedy jen kořenový certifikát do složky „Trusted Root Certification Authorities“ (vyexportovaný soubor „CARoot.cer“).

2.3. Instalace klientského certifikátu

Klientský certifikát se instaluje na počítač nebo server, ze kterého se bude volat:

1. Spusťte konzoli „MMC“ a přidejte modul „Certificates“ týmž postupem jako výše.
2. Zvolte „My user account“, má-li se certifikátem prokazovat přihlášený uživatel (typicky prohlížeč), nebo „Computer account“, má-li se jím prokazovat služba či naplánovaná úloha.
3. Do složky „Personal“ naimportujte klientský certifikát včetně privátního klíče (například „ClientCert.pfx“).
4. Instaluje-li se certifikát do úložiště počítače, přidejte účtu, pod kterým volající aplikace běží, oprávnění k privátnímu klíči — pravým tlačítkem na certifikát, „All Tasks / Manage Private Keys…“. Bez toho aplikace certifikát vidí, ale nemůže se jím prokázat.
5. Nedůvěřuje-li klientský počítač vydavateli serverového certifikátu (typicky u testovacích certifikátů), naimportujte na něj i kořenový certifikát do složky „Trusted Root Certification Authorities“.

3. Nastavení IIS

3.1. Instalace role

Mapování certifikátu na účet Windows obsluhuje samostatná role webového serveru, kterou je nutné doinstalovat:

1. Spusťte aplikaci „Server Manager“ a zvolte „Add roles and features“.
2. V části „Server Roles“ rozbalte „Web Server (IIS) / Web Server / Security“ a zaškrtněte „IIS Client Certificate Mapping Authentication“.
3. Průvodce dokončete tlačítkem „Install“.

Ve výčtu je i podobně pojmenovaná role „Client Certificate Mapping Authentication“ (bez počátečního „IIS“). Ta mapuje certifikáty na účty prostřednictvím Active Directory a konfiguruje se jinak; postup v této příručce ji nepoužívá.

Bude-li se certifikát vyhodnocovat v kódu aplikace (viz kapitola 4), není role potřeba vůbec.

3.2. Nastavení bindingu HTTPS

1. Spusťte „IIS Manager“ („Správce služby IIS“) a v seznamu „Sites“ vyberte cílový web.
2. V části „Actions“ zvolte „Bindings…“ a tlačítkem „Add…“ přidejte vazbu typu „https“ na portu 443.
3. V poli „SSL certificate“ vyberte serverový certifikát nainstalovaný v předchozí kapitole.

Detailní popis pořízení certifikátu SSL od certifikační autority je uveden v samostatné příručce Instalace NET Genium – webový server.

3.3. Vyžádání klientského certifikátu

1. V „IIS Manager“ vyberte aplikaci (nebo celý web), která má být certifikátem chráněná, a otevřete „SSL Settings“ („Nastavení SSL“).
2. Zaškrtněte „Require SSL“ a v části „Client certificates“ zvolte jednu z voleb:

Volba	Chování
Ignore	Certifikát se od klienta vůbec nevyžaduje (výchozí stav)
Accept	Certifikát se vyžádá, ale požadavek projde i bez něj — vyhodnocení je na aplikaci
Require	Bez platného klientského certifikátu server požadavek odmítne se stavovým kódem 403.7

Volba „Require“ patří k mapování na účet Windows, volba „Accept“ k vyhodnocení v kódu aplikace — ta umožní aplikaci odpovědět vlastní chybovou hláškou místo stránky serveru.

3.4. Mapování certifikátu na účet Windows (1:1)

Mapování „jeden na jednoho“ přiřadí konkrétnímu certifikátu konkrétní účet Windows. Nastavuje se v konfiguraci webu, nikoli ve zdrojovém kódu aplikace:

1. V „IIS Manager“ vyberte v seznamu „Sites“ web, pod kterým aplikace běží, a otevřete „Configuration Editor“.
2. V poli „Section“ vyberte „system.webServer/security/authentication/iisClientCertificateMappingAuthentication“.
3. Nastavte „enabled“ na „True“ a „oneToOneCertificateMappingsEnabled“ na „True“.
4. U položky „oneToOneMappings“ klikněte na „…“, tlačítkem „Add“ přidejte pravidlo a vyplňte:
   1. „enabled“ — „True“
   2. „userName“ — účet Windows, pod kterým má požadavek běžet (běžně tentýž technologický účet, pod kterým běží aplikační pool)
   3. „password“ — heslo k tomuto účtu
   4. „certificate“ — veřejný klíč klientského certifikátu zakódovaný do Base64 (viz níže)
5. Změny uložte tlačítkem „Apply“.

Hodnotu pro pole „certificate“ je nejspolehlivější získat z PowerShellu — výsledkem je jeden dlouhý řádek bez zalomení, který stačí zkopírovat:

[Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\cert\ClientCert.cer"))

• Certifikát musí být vyexportovaný bez privátního klíče (soubor „cer“). Privátní klíč zná jen klient.
• Otevřete-li si soubor v textovém editoru, je to tentýž řetězec — ovšem bez řádků „-----BEGIN CERTIFICATE-----“ a „-----END CERTIFICATE-----“ a bez zalomení řádků. Ruční úprava v editoru je proto zbytečná a chybová.

Sekci „iisClientCertificateMappingAuthentication“ nelze nastavit v souboru „Web.config“ dané aplikace. Je v konfiguraci serveru uzamčená (atribut „overrideModeDefault“ má hodnotu „Deny“), takže se otevírá „Configuration Editor“ na úrovni serveru nebo webu — ne na úrovni vnořené aplikace. Zapsané hodnoty skončí v souboru „applicationHost.config“.

3.5. Mapování více certifikátů na jeden účet (N:1)

Mapování „více na jednoho“ neporovnává celý certifikát, ale jen vybraná pole — typicky vydavatele a předmět. Nastavuje se v téže sekci „Configuration Editor“, jen místo „oneToOneMappings“ se vyplní „manyToOneMappings“ a zapne se „manyToOneCertificateMappingsEnabled“. Každé pravidlo má vedle účtu a hesla i seznam pravidel („rules“) s polem certifikátu, porovnávanou hodnotou a příznakem, zda musí hodnota souhlasit přesně.

Tato varianta se hodí všude tam, kde certifikáty vydává jedna autorita a je jich víc nebo se obměňují — pravidlo přežije obnovu certifikátu, kdežto mapování 1:1 je po obnově nutné přepsat novým veřejným klíčem.

4. Ověření certifikátu v kódu aplikace

Druhá varianta žádnou roli IIS ani účet Windows nepotřebuje. V „SSL Settings“ se nastaví „Client certificates: Accept“ (nebo „Require“) a certifikát si vyhodnotí sama aplikace — u API tedy metoda „Application_BeginRequest“ v souboru „Global.asax.cs“ popsaná v příručce API:

System.Web.HttpClientCertificate cert = Request.ClientCertificate;

if (!cert.IsPresent || !cert.IsValid)
{
    throw new UnauthorizedAccessException("Missing or invalid client certificate");
}

string thumbprint = BitConverter.ToString(cert.GetCertHash()).Replace("-", "");

if (!"A1B2C3…".Equals(thumbprint, StringComparison.OrdinalIgnoreCase))
{
    throw new UnauthorizedAccessException("Unknown client certificate: " + cert.Subject);
}

• Vlastnost „IsPresent“ říká, zda klient certifikát vůbec poslal, „IsValid“, zda prošel ověřením na straně IIS.
• Otisk („thumbprint“) je nejpřísnější kritérium — identifikuje právě jeden certifikát, takže po jeho obnově je nutné hodnotu v aplikaci změnit. Volnějším kritériem je dvojice „Issuer“ a „Subject“, která obnovu certifikátu přežije.
• Seznam povolených certifikátů nepatří do zdrojového kódu — uložte ho do databáze (obdobně jako tokeny API v tabulce „ng_apitoken“) nebo do konfiguračního souboru, ať se nová protistrana přidává bez překladu aplikace.
• Toto ověření nenahrazuje nastavení IIS. Je-li v „SSL Settings“ ponechána volba „Ignore“, žádný certifikát nedorazí a vlastnost „IsPresent“ je vždy nepravdivá.

5. Proxy server a kontrola odvolaných certifikátů

Je-li v certifikátu uvedený seznam odvolaných certifikátů („CRL“) nebo adresa služby „OCSP“, server si při ověřování řetězce tyto adresy stahuje z internetu. Nemá-li k internetu přímý přístup, ověření se zdrží a nakonec selže, přestože je certifikát v pořádku.

Windows mají dvě nezávislá nastavení proxy serveru a pro tuto kontrolu je rozhodující to druhé:

• WinINet — nastavení používané prohlížeči a interaktivními aplikacemi (dialog „Možnosti internetu“). Na ověřování certifikátů vliv nemá.
• WinHTTP — nastavení používané službami systému, tedy i kontrolou platnosti certifikátů. Právě to je potřeba nastavit.

Aktuální stav se zjistí a nastaví v příkazovém řádku spuštěném jako správce:

netsh winhttp show proxy
netsh winhttp set proxy proxy.priklad.cz:8080 bypass-list="<local>"

Vypíše-li první příkaz „Direct access (no proxy server)“ a server přitom do internetu přímý přístup nemá, je nutné proxy server nastavit druhým příkazem. Adresu proxy serveru dodá správce sítě zákazníka.

6. Řešení problémů

Autentizace probíhá na úrovni IIS, takže v logu aplikace ani v logu NET Genia se neúspěšný pokus neobjeví — chybu je nutné hledat ve stavovém kódu odpovědi a v protokolech IIS.

6.1. Stavové kódy odpovědi

Kód	Význam a co zkontrolovat
403.7	Klient neposlal certifikát — není nainstalovaný, nemá „Client Authentication“, nebo ho klient nenabídl, protože jeho vydavatele server neuvedl jako důvěryhodného
403.13	Certifikát je odvolaný, nebo se stav odvolání nepodařilo ověřit (viz kapitola 5)
403.16	Certifikátu nelze důvěřovat — kořenová autorita chybí v úložišti serveru, nebo v něm jsou certifikáty, které tam nepatří (viz kapitola 6.3)
401.1	Certifikát se sice namapoval, ale přihlášení namapovaným účtem selhalo — chybné jméno nebo heslo v mapování

6.2. Protokolování IIS

Podrobnosti k odmítnutému požadavku vypíše „Failed Request Tracing“:

1. V „IIS Manager“ vyberte web a v části „Actions“ zvolte „Failed Request Tracing…“; zaškrtněte „Enable“ a potvrďte adresář pro protokoly.
2. U dotčené aplikace otevřete „Failed Request Tracing Rules“ a tlačítkem „Add…“ přidejte pravidlo — obvykle pro všechen obsah („All content“) a pro stavové kódy „401-403“.
3. Zopakujte neúspěšný požadavek a otevřete vzniklý soubor „fr…xml“ v prohlížeči.

Dorazil-li certifikát až do aplikace, vypíše jeho údaje report „Headers“ v nástrojích NET Genia — zobrazuje obsah kolekcí „Request.Headers“, „Request.Cookies“ a „Request.ClientCertificate“. Detailní popis reportů je uveden v samostatné příručce Reporty.

6.3. Obsah úložiště důvěryhodných kořenových autorit

V úložišti „Trusted Root Certification Authorities“ smějí být pouze certifikáty podepsané sebou samými — tedy skutečné kořenové autority. Certifikát, který tam nepatří, dokáže ověřování klientských certifikátů rozbít, i když je vše ostatní nastavené správně.

Poznají se tak, že mají rozdílné hodnoty ve sloupcích „Issued to“ a „Issued by“. Jejich seznam vypíše PowerShell:

Get-ChildItem Cert:\LocalMachine\Root |
    Where-Object { $_.Issuer -ne $_.Subject } |
    Format-List Subject, Issuer, Thumbprint

Vypíše-li příkaz nějaký certifikát, přesuňte ho do úložiště, kam patří (obvykle „Intermediate Certification Authorities“), restartujte server a pokus zopakujte.

6.4. Další časté příčiny

• Obnovený certifikát. Mapování 1:1 i kontrola otisku v kódu jsou vázané na konkrétní certifikát. Po jeho obnově přestane autentizace fungovat a je nutné zapsat nový veřejný klíč nebo otisk; proti tomu je odolné mapování N:1 podle vydavatele a předmětu.
• Přenos konfigurace na jiný server. Heslo v mapování je v souboru „applicationHost.config“ zašifrované klíčem daného serveru, takže zkopírovaná konfigurace na jiném serveru nefunguje — mapování je nutné vyplnit znovu.
• Certifikát se v prohlížeči vůbec nenabídne. Klient nabízí pouze certifikáty vydané autoritou ze seznamu, který mu server poslal. Chybí-li kořenová autorita v úložišti serveru, nabídka zůstane prázdná a požadavek skončí kódem 403.7.
• Vypršelá platnost. Platnost klientského i serverového certifikátu hlídejte s předstihem — vypršením certifikátu se integrace zastaví ze dne na den.

Postup nastavení ověřování anonymním přístupem a systémem Windows je uveden v samostatné příručce Instalace NET Genium – webový server.