Mutual TLS (mTLS) Certificate Guide

Mutual TLS (mTLS) Certificate Guide

Mutual TLS (mTLS) requires both the server and the client to present X.509 certificates during the TLS handshake, providing bidirectional cryptographic authentication. In standard TLS, only the server presents a certificate; the client verifies the server's identity but the server has no cryptographic proof of the client's identity. In mTLS, the server sends a CertificateRequest message during the handshake, the client responds with its own certificate, and the server verifies that certificate against its configured CA trust store. Consequently, only clients holding a certificate signed by a trusted CA can complete the handshake at all, regardless of any credentials in the request body. mTLS is widely used in service mesh architectures like Istio and Linkerd, zero-trust network designs, and B2B API integrations that require stronger authentication than API keys or OAuth tokens.

mTLS certificate requirements versus server certificates

Client certificates for mTLS share the same X.509 structure as server certificates but differ in their Extended Key Usage extension. A server certificate includes the TLS Web Server Authentication OID (1.3.6.1.5.5.7.3.1) in its Extended Key Usage extension. A client certificate for mTLS includes the TLS Web Client Authentication OID (1.3.6.1.5.5.7.3.2)¹.

The Subject distinguished name typically identifies the client rather than a domain name: for example, a client certificate for a microservice might have CN=payment-service, or a client certificate for a B2B partner might have O=Acme Corp, CN=partner-api. Furthermore, the CA that issues client certificates may be different from the CA that issues server certificates; many mTLS deployments use a private internal CA for client certificates while using a publicly trusted CA for server certificates. Inspecting a client certificate in the CapyToolkit Certificate Inspector confirms its Extended Key Usage OIDs, the Issuer, and the validity window, so you can verify the EKU before deployment.

How EKU OIDs decide which purpose a certificate can serve

Extended Key Usage is not a suggestion; it is a constraint that compliant TLS libraries enforce. Server-only certificates that lack the Client Authentication OID cannot be presented during a CertificateRequest without the peer rejecting them, and client-only certificates that lack the Server Authentication OID fail when accidentally configured on a web server. Software PKI tooling sometimes issues certificates with both OIDs to allow dual use, but that weakens the separation between client and server roles and makes a compromised client certificate usable for impersonating a server. When you generate a client certificate for mTLS, checking the EKU field before deployment catches misconfigured templates before they cause handshake failures in production.

A related check is to confirm the CA that issued the client certificate is the one the server actually trusts. mTLS fails in subtle ways when the client certificate chains to a different internal CA than the server's trust list expects, even when the certificate is otherwise valid. The CapyToolkit Certificate Inspector shows the Issuer and the chain for any client certificate, so you can compare it against the CA bundle the server is configured to verify before rolling out the connection.

Setting up and verifying mTLS in server configuration

Configuring mTLS on a server requires setting up client certificate verification against a specified CA trust list. In nginx, the ssl_client_certificate directive points to the CA certificate bundle that signed client certificates, and ssl_verify_client on enables verification². In Node.js, the tls.createServer options object accepts ca (an array of CA certificates) and requestCert: true plus rejectUnauthorized: true³. The server uses the ssl_verify_depth or equivalent setting to limit the number of intermediates in the client certificate chain it will validate. Consequently, a misconfigured ssl_verify_depth that is too shallow causes valid client certificates signed through an intermediate to fail validation even when the chain is otherwise correct. The CapyToolkit Certificate Inspector can parse the client certificate to show its Issuer and Extended Key Usage OIDs, confirming the certificate carries the correct authentication purpose before configuring the server.

When ssl_verify_depth silently rejects valid client certificates

A deployment that switches from a direct CA issuance pattern to an intermediate CA often keeps the ssl_verify_depth setting at its default value of 1, which only validates client certificates signed directly by a trusted CA. Client certificates that chain through the new intermediate then fail validation even though every certificate in the chain is valid and signed correctly, because the verifier does not traverse deeply enough to reach a trusted root. The fix is to set ssl_verify_depth to at least 2 when an intermediate CA sits between the client certificate and the trust store, or higher when the chain has additional issuing layers. A quick way to detect this failure mode is to inspect the client certificate chain in the Certificate Inspector and count the intermediates between the leaf and the trusted root, then configure the depth to match.

mTLS in service mesh architectures and SPIFFE SVIDs

Service meshes like Istio and Linkerd use mTLS as the default authentication mechanism between services, issuing short-lived client and server certificates automatically via their control planes. Istio's istiod component issues SPIFFE-format X.509 SVIDs (SPIFFE Verifiable Identity Documents) to each workload, embedding the workload's identity as a URI SAN in the SPIFFE format: spiffe://cluster-id/ns/namespace/sa/service-account⁴. These certificates typically have 24-hour validity and rotate automatically. Consequently, mTLS in a service mesh eliminates the need to manage certificates manually for service-to-service communication, while still providing cryptographic proof of each service's identity. The CapyToolkit Certificate Inspector can parse SPIFFE certificates: paste the PEM and look for the URI SAN entry containing the SPIFFE ID in the Extensions section of the expanded card.

How short-lived SVIDs trade validity windows for revocation-free operation

Service meshes can afford one hour of validity because the control plane reissues certificates without operator intervention and workloads receive new credentials before the old ones expire. A shorter validity window limits the damage from a leaked private key, since a stolen certificate becomes useless within hours regardless of whether it has been revoked. Traditional revocation mechanisms like CRLs and OCSP introduce network latency and caching concerns that are unacceptable when every service connects to every other service dozens of times per second. By pairing short lifetimes with automated issuance, service meshes sidestep the revocation problem entirely while still maintaining strong cryptographic identity for every connection⁵.

When to use this

Use this guide when implementing service-to-service authentication in a microservices architecture, when setting up mTLS for a B2B API integration that requires stronger authentication than shared secrets, or when troubleshooting mTLS handshake failures. It also applies when designing the certificate issuance workflow for client certificates: unlike server certificates, client certificates for mTLS require a private CA or managed PKI service rather than a publicly trusted CA, and the Extended Key Usage extension must carry the Client Authentication OID. Furthermore, use this guide when migrating from API key authentication to mTLS, since the migration requires changes on both the server side and all clients before the cutover to avoid downtime. Building on this, apply the SPIFFE section whenever you are evaluating service mesh options, since understanding how Istio and Linkerd manage certificate lifecycles affects your choice of mesh and your observability requirements for certificate rotation events.

Examples

SSL Certificates for API Security

SSL certificates protect API endpoints the same way they protect web browser connections, but API security introduces additional certificate considerations beyond basic HTTPS. API consumers often enforce strict certificate validation, implement certificate pinning, or require mutual TLS where the client also presents a certificate. Unlike browser users who see a warning and can click through, API clients typically reject invalid certificates outright and throw errors that immediately surface in logs. Consequently, certificate problems on API endpoints cause immediate, visible failures that stop integration partners from making progress. This guide covers how to configure and verify certificates for API security, the specific fields API clients check, and when certificate pinning or mTLS authentication should supplement standard TLS for high-security API integrations.

Certificate validation in API clients

API clients, whether HTTP libraries, SDKs, or integration frameworks, perform the same chain validation as browsers but with stricter failure behavior and no user override option. Python's requests library validates certificates by default¹; curl validates by default²; Java's HttpURLConnection validates by default³. When a certificate is expired, has a hostname mismatch, or presents an incomplete chain, these clients throw exceptions that immediately terminate the request rather than showing a warning. Yet the most dangerous API security pattern is disabling certificate validation entirely for debugging purposes and accidentally leaving it disabled in production code. The verify=False parameter in Python requests, the -k flag in curl, and ALLOW_ALL_HOSTNAME_VERIFIER patterns in Java all suppress TLS protection completely. Auditing API client code for these patterns is as important as auditing the certificates the server presents.

When verify=False becomes a production vulnerability

The quickest way to silence a certificate error during development is to disable verification entirely, and the most common mistake is leaving that shortcut in code that reaches production. Python's requests accepts verify=False, curl accepts -k and --insecure, and Java's SSLContext can be configured with a TrustManager that accepts every certificate without inspection. These bypasses remove every protection TLS provides, allowing man-in-the-middle interception of every request without either side noticing. Temporary exceptions for self-signed certificates during testing become permanent holes when environments are shared or configuration flags leak between deployments. For most teams, a safer approach is to add the specific CA to a custom trust bundle and keep verification enabled, preserving the same code path in development and production while still covering internal PKI that public roots do not trust.

Hostname validation and Subject Alternative Names for API endpoints

API endpoints often have hostnames that differ from web-facing domains: api.example.com, v2.api.example.com, or internal-api.example.com. Each hostname an API client uses to connect must appear in the server certificate's Subject Alternative Names extension. Consequently, a wildcard certificate for *.example.com covers api.example.com but not v2.api.example.com (two labels deep) or internal-api.internal.example.com⁴. Furthermore, API clients connecting to private or internal endpoints by IP address require the IP address to appear as an iPAddress SAN rather than a DNS SAN. Connecting by IP and having only a DNS SAN for the hostname causes hostname verification to fail. Inspect API certificates using the Certificate Inspector to verify that every hostname variant your client uses appears in the SAN extension before troubleshooting other potential causes.

Why hostnames and IP addresses need different SAN types

A common misconfiguration when securing internal APIs is issuing a certificate with only dNSName SAN entries while clients connect directly by IP. Hostname verification compares the connection target against the SAN values using rules defined in RFC 6125: a dNSName entry never matches an IPv4 or IPv6 address, so the only way to make an IP-based connection succeed is to include an iPAddress SAN entry for that exact IP. When the API is later load-balanced behind a different address, the certificate must be reissued because IP SANs are literal values, not patterns. For teams that prefer to avoid reissuing certificates on every infrastructure change, the more sustainable path is to assign the internal API a stable DNS name and use dNSName SANs that follow the service as it moves between clusters.

Certificate pinning for API security hardening

Certificate pinning supplements standard certificate validation by requiring the server to present a specific certificate or key, not just any certificate from a trusted CA⁵. An API client that pins a certificate fingerprint compares the SHA-256 fingerprint of the received certificate against a stored expected value and rejects any connection that does not match, even from a trusted CA. This defeats attacks where an attacker obtains a fraudulent certificate from a compromised CA, because the pinned fingerprint will not match the fraudulent certificate.

Why pinning operational discipline decides whether it helps or hurts

Yet pinning requires operational discipline: every time the server certificate renews, the pinned fingerprint must be updated in the client before the old certificate expires. Public-key pinning, which pins the fingerprint of the server's public key rather than the entire certificate, reduces this churn when the same key pair is reused across renewals. Teams that adopt pinning without a plan for updating clients before renewal deadlines introduce a new denial-of-service vector instead of closing an attack surface. The safest rollout pattern includes a fallback pin that is never used in production, allowing the new pin to be deployed and validated for a full rotation cycle before the old one is retired.

Deciding when pinning is worth the operational cost

Building on this, certificate pinning is most appropriate for high-security B2B API integrations where both sides control the client application and can coordinate certificate rotation in advance. Mobile applications that connect to a fixed backend, embedded devices managed through a single vendor, and partner APIs with a small number of known consumers all qualify as scenarios where the maintenance burden is justified by the reduction in acceptable CA risk. By contrast, public APIs with hundreds of independent clients experience pin Update failures too frequently to operate safely without an overwhelming support burden, and in those cases standard CA validation with monitoring provides better uptime at equivalent security.

For routine operations, the cheapest way to avoid pinning mistakes is to keep renewal and client updates on the same calendar. When the server certificate rotates, update the pinned fingerprint in the same change rather than as a separate follow-up that someone forgets. The CapyToolkit Certificate Inspector displays the SHA-256 fingerprint in the General section, so you can copy the exact fingerprint for pinning without recomputing it by hand.

When to use this

Use this guide when designing TLS configuration for a new API endpoint, when troubleshooting certificate validation failures from API clients, or when evaluating whether certificate pinning or mTLS is appropriate for a specific API security requirement. It also applies when reviewing API client code during a security audit: disabling certificate validation is a common development shortcut that persists into production code, and identifying those patterns requires knowing what to look for across each language and HTTP library. Furthermore, use this guide when onboarding an integration partner who will consume your API, since partners using strict validation or pinning need the certificate's SHA-256 fingerprint, the CA chain, and the renewal schedule in advance. Building on this, apply these checks whenever you add a new hostname or IP address to an existing API endpoint's certificate, since clients validating specific SAN entries will fail if the updated SAN list is not reflected in the deployed certificate.

Examples