Dlaczego mój certyfikat klienta nie działa? Rozwiązywanie problemów z mTLS po stronie klienta

Awaria certyfikatu serwerowego jest zwykle głośna i ogólna — “niezaufany”, czerwona kłódka. Awaria certyfikatu klienta w mTLS jest cichsza i bardziej specyficzna: zerwane połączenie, ogólny błąd 403, albo alert TLS bez wyjaśnienia. Sam certyfikat rzadko jest faktycznym problemem — to, jak jest prezentowany, zwykle jest.

Krok 1: Potwierdź, że klient faktycznie wysyła certyfikat

Zanim zaczniesz debugować certyfikat, potwierdź, że w ogóle bierze udział w handshake’u.

openssl s_client -connect api.example.com:443 -cert client.pem -key client-key.pem -CAfile ca.pem -state </dev/null

Uruchom tę samą komendę bez -cert/-key i porównaj oba wyniki. Jeśli serwer zachowuje się identycznie w obu przypadkach, klient nie prezentuje certyfikatu — to problem konfiguracji klienta (zła ścieżka, zła zmienna środowiskowa, biblioteka HTTP niepodpięta do wysyłania certyfikatu), a nie problem certyfikatu. Napraw to najpierw — wszystko poniżej zakłada, że certyfikat faktycznie dociera do serwera.

Krok 2: Zweryfikuj, że klucz prywatny faktycznie pasuje do certyfikatu

Najczęstsza cicha awaria. Niedopasowana para klucz/certyfikat nie daje żadnego opisowego błędu — handshake po prostu zawodzi.

openssl x509 -noout -modulus -in client.pem | openssl md5
openssl rsa -noout -modulus -in client-key.pem | openssl md5

Jeśli te dwa hashe się nie zgadzają, łączysz certyfikat ze złym kluczem — często efekt regeneracji jednej połowy pary i zapomnienia o redystrybucji drugiej.

Krok 3: Sprawdź Extended Key Usage (EKU)

openssl x509 -in client.pem -noout -text | grep -A1 "Extended Key Usage"

Szukasz TLS Web Client Authentication. Certyfikaty wygenerowane z szablonu certyfikatu serwerowego — bardzo łatwy błąd przy ręcznym generowaniu certów albo przy skrypcie generującym je z wewnętrznego CA — często mają zamiast tego TLS Web Server Authentication, albo w ogóle nie mają ograniczenia EKU. Część stosów TLS jest w tej kwestii pobłażliwa; restrykcyjne (a większość bram mTLS taka jest) odrzucają handshake wprost, z błędem, który rzadko wspomina EKU po nazwie.

Krok 4: Sprawdź, czy certyfikat wygasł — i sprawdź też CA klienta

openssl x509 -in client.pem -noout -dates
openssl x509 -in ca.pem -noout -dates

Ta sama zasada co przy troubleshootingu po stronie serwera: sprawdź cały łańcuch, nie tylko certyfikat liściowy. CA klienta, które wygasło albo zostało rotowane bez redystrybucji nowych certyfikatów klienta, sprawi, że zawiedzie każdy klient wystawiony pod starym CA.

Krok 5: Potwierdź, że serwer faktycznie ufa CA tego klienta

To sprawdzenie po stronie serwera, ale to najczęstsza pierwotna przyczyna, gdy kroki 1–4 są już wykluczone. Certyfikat klienta może być całkowicie ważny i mimo to zostać odrzucony, jeśli CA, które go podpisało, nie znajduje się na liście zaufanych CA po stronie serwera (SSLCACertificateFile, ConfigMap w Kubernetes używany do weryfikacji mTLS, bundle zaufanych CA w bramie API — dokładny mechanizm zależy od tego, co terminuje TLS).

openssl x509 -in client.pem -noout -issuer

Porównaj tego issuera z tym, czemu serwer faktycznie jest skonfigurowany ufać. Niedopasowanie w tym miejscu wygląda z perspektywy klienta identycznie jak każda inna awaria na tej liście — jedyny sposób, żeby je odróżnić, to sprawdzenie konfiguracji serwera wprost.

Krok 6: Wyklucz niejednoznaczność przy wielu certyfikatach

Jeśli środowisko klienta ma dostępny więcej niż jeden certyfikat — kilka wpisów w keystore, kilka certyfikatów zainstalowanych w przeglądarce, runner CI z certyfikatami pozostałymi po poprzednim zadaniu — potwierdź, że wybierany jest faktycznie ten właściwy. curl --cert i odpowiadające mu jawne flagi eliminują tę niejednoznaczność; przeglądarki i część SDK wybierają automatycznie i mogą wybrać źle.

Najczęstsze przyczyny, w kolejności jak często się potwierdzają

Przyczyna	Jak sprawdzić
Niedopasowanie klucza i certyfikatu	Krok 2 — porównanie hasha modulusu
Serwer nie ufa CA klienta	Krok 5 — porównaj issuera z listą zaufanych CA serwera
Brakujące/złe Extended Key Usage	Krok 3 — grep EKU certyfikatu
Klient w ogóle nie wysyła certyfikatu	Krok 1 — diff handshake’ów z/bez -cert
Wygasły certyfikat klienta albo CA klienta	Krok 4 — sprawdź daty obu
Wybrano zły certyfikat spośród kilku	Krok 6

Certyfikaty po stronie klienta zawodzą po cichu — to prawdziwy problem

Każda przyczyna powyżej ma jedną wspólną cechę: nic głośno nie ogłasza, która to jest. Awaria certyfikatu serwerowego przynajmniej mówi użytkownikowi, że coś jest nie tak; awaria certyfikatu klienta zwykle po prostu wygląda jak “żądanie nie zadziałało”. To kosztowne do debugowania na bieżąco, i dokładnie ten rodzaj problemu jest tani do zapobiegania — wiedza, jakie certyfikaty klienta istnieją, kto je wystawił, do jakiego CA się odwołują i kiedy wygasają, zanim czyjeś połączenie mTLS zacznie po cichu zawodzić. Ten problem inwentaryzacji i terminów ważności, dla każdego certyfikatu — klienta czy serwera — śledzi Certyfizer.