<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>mTLS | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/mtls/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 09:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/mtls/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>HAProxy mTLS: Securing API Access with Mutual TLS Authentication</title><link>https://blog.bsdserver.nl/haproxy-mtls-securing-api-access-with-mutual-tls-authentication/</link><guid isPermaLink="false">693b755d79eb54000160a60f</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:52:29 +0000</pubDate><description>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates.</description><category>HAProxy</category><category>mTLS</category><category>Security</category><category>TLS</category><category>Certificates</category><category>API</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-mtls.png" medium="image"/><content:encoded><![CDATA[<p>Mutual TLS (mTLS) provides strong authentication by requiring both client and server to present certificates. API keys and passwords can leak and be replayed; a client certificate proves identity during the TLS handshake, before any request reaches your application.</p>
<p>This guide builds a small internal CA, configures HAProxy to require client certificates, passes the certificate identity to the backends, authorizes by CN, OU or fingerprint, and revokes certificates with a CRL.</p>
<h2 id="what-is-mtls">What is mTLS? <a class="anchor" data-pagefind-ignore href="#what-is-mtls" aria-label="Link to this section">#</a></h2>
<p>In standard TLS, only the server presents a certificate. With mTLS:</p>
<ol>
<li>Server presents its certificate to the client</li>
<li>Client verifies the server certificate</li>
<li>Client presents its certificate to the server</li>
<li>Server verifies the client certificate</li>
</ol>
<p>Both parties are authenticated. HAProxy does the client check, so the backends do not need any TLS code.</p>
<h2 id="why-mtls">Why mTLS? <a class="anchor" data-pagefind-ignore href="#why-mtls" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Service-to-service communication</strong>: Microservices authenticating each other</li>
<li><strong>API security</strong>: Authenticating API clients without passwords</li>
<li><strong>Zero-trust networks</strong>: Verifying identity at every connection</li>
<li><strong>IoT devices</strong>: Authenticating embedded devices</li>
<li><strong>B2B integrations</strong>: Partner API access with certificate-based auth</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> for machine clients you control or issue certificates to: services, devices, partners.</li>
<li><strong>Skip it</strong> for public websites and end users in browsers. Installing certificates on user devices is painful; use OAuth or sessions instead.</li>
</ul>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Internal CA</td>
					<td>A locked-down host (here: the HAProxy host)</td>
					<td>Signs server and client certificates, publishes the CRL.</td>
			</tr>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Terminates TLS, checks the client certificate against the CA and CRL, applies ACLs, adds identity headers.</td>
			</tr>
			<tr>
					<td>Backends</td>
					<td>App servers</td>
					<td>Receive plain HTTP plus <code>X-Client-*</code> headers.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Services, devices, partners</td>
					<td>Present a certificate signed by the CA.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client connects with its certificate → HAProxy verifies it against <code>ca-file</code> and <code>crl-file</code> → ACLs on CN/OU allow or deny → request goes to a backend with the client identity in headers.</p>
<h2 id="certificate-infrastructure-setup">Certificate Infrastructure Setup <a class="anchor" data-pagefind-ignore href="#certificate-infrastructure-setup" aria-label="Link to this section">#</a></h2>
<h3 id="create-a-certificate-authority-ca">Create a Certificate Authority (CA) <a class="anchor" data-pagefind-ignore href="#create-a-certificate-authority-ca" aria-label="Link to this section">#</a></h3>
<p>Your own CA decides who is a valid client: HAProxy trusts every certificate it signs. Use a private CA, never a public one, or anyone with a public certificate gets in.</p>
<p>What the <code>openssl.cnf</code> sections do:</p>
<table>
	<thead>
			<tr>
					<th>Section</th>
					<th>Use</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>CA_default</code></td>
					<td>Paths, 365-day default validity, 30-day CRL validity. <code>copy_extensions = copy</code> keeps the SAN from the CSR.</td>
			</tr>
			<tr>
					<td><code>policy_strict</code></td>
					<td>Only <code>commonName</code> is required in requests.</td>
			</tr>
			<tr>
					<td><code>v3_ca</code></td>
					<td>Extensions for the CA certificate itself.</td>
			</tr>
			<tr>
					<td><code>usr_cert</code></td>
					<td>Client certificates: <code>extendedKeyUsage = clientAuth</code>.</td>
			</tr>
			<tr>
					<td><code>server_cert</code></td>
					<td>Server certificates: <code>extendedKeyUsage = serverAuth</code>.</td>
			</tr>
	</tbody>
</table>
<p>The CA key is encrypted with a passphrase (<code>-aes256</code>) and the CA certificate is valid for 10 years.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Create CA directory structure</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/ca/<span class="o">{</span>certs,crl,newcerts,private,csr<span class="o">}</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">700</span> /etc/haproxy/ca/private
</span></span><span class="line"><span class="cl">touch /etc/haproxy/ca/index.txt
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="m">1000</span> &gt; /etc/haproxy/ca/serial
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create CA configuration</span>
</span></span><span class="line"><span class="cl">cat &gt; /etc/haproxy/ca/openssl.cnf <span class="s">&lt;&lt; &#39;EOF&#39;
</span></span></span><span class="line"><span class="cl"><span class="s">[ca]
</span></span></span><span class="line"><span class="cl"><span class="s">default_ca = CA_default
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[CA_default]
</span></span></span><span class="line"><span class="cl"><span class="s">dir               = /etc/haproxy/ca
</span></span></span><span class="line"><span class="cl"><span class="s">certs             = $dir/certs
</span></span></span><span class="line"><span class="cl"><span class="s">crl_dir           = $dir/crl
</span></span></span><span class="line"><span class="cl"><span class="s">new_certs_dir     = $dir/newcerts
</span></span></span><span class="line"><span class="cl"><span class="s">database          = $dir/index.txt
</span></span></span><span class="line"><span class="cl"><span class="s">serial            = $dir/serial
</span></span></span><span class="line"><span class="cl"><span class="s">private_key       = $dir/private/ca.key
</span></span></span><span class="line"><span class="cl"><span class="s">certificate       = $dir/certs/ca.crt
</span></span></span><span class="line"><span class="cl"><span class="s">default_md        = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">default_days      = 365
</span></span></span><span class="line"><span class="cl"><span class="s">default_crl_days  = 30
</span></span></span><span class="line"><span class="cl"><span class="s">copy_extensions   = copy
</span></span></span><span class="line"><span class="cl"><span class="s">preserve          = no
</span></span></span><span class="line"><span class="cl"><span class="s">policy            = policy_strict
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[policy_strict]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName             = optional
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName     = optional
</span></span></span><span class="line"><span class="cl"><span class="s">localityName            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName        = optional
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName  = optional
</span></span></span><span class="line"><span class="cl"><span class="s">commonName              = supplied
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress            = optional
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req]
</span></span></span><span class="line"><span class="cl"><span class="s">default_bits        = 4096
</span></span></span><span class="line"><span class="cl"><span class="s">distinguished_name  = req_distinguished_name
</span></span></span><span class="line"><span class="cl"><span class="s">string_mask         = utf8only
</span></span></span><span class="line"><span class="cl"><span class="s">default_md          = sha256
</span></span></span><span class="line"><span class="cl"><span class="s">x509_extensions     = v3_ca
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[req_distinguished_name]
</span></span></span><span class="line"><span class="cl"><span class="s">countryName                     = Country Name (2 letter code)
</span></span></span><span class="line"><span class="cl"><span class="s">stateOrProvinceName             = State or Province Name
</span></span></span><span class="line"><span class="cl"><span class="s">localityName                    = Locality Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationName                = Organization Name
</span></span></span><span class="line"><span class="cl"><span class="s">organizationalUnitName          = Organizational Unit Name
</span></span></span><span class="line"><span class="cl"><span class="s">commonName                      = Common Name
</span></span></span><span class="line"><span class="cl"><span class="s">emailAddress                    = Email Address
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[v3_ca]
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid:always,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = critical, CA:true
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, cRLSign, keyCertSign
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[usr_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = client, email
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Client Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = clientAuth, emailProtection
</span></span></span><span class="line"><span class="cl"><span class="s">
</span></span></span><span class="line"><span class="cl"><span class="s">[server_cert]
</span></span></span><span class="line"><span class="cl"><span class="s">basicConstraints = CA:FALSE
</span></span></span><span class="line"><span class="cl"><span class="s">nsCertType = server
</span></span></span><span class="line"><span class="cl"><span class="s">nsComment = &#34;Server Certificate&#34;
</span></span></span><span class="line"><span class="cl"><span class="s">subjectKeyIdentifier = hash
</span></span></span><span class="line"><span class="cl"><span class="s">authorityKeyIdentifier = keyid,issuer:always
</span></span></span><span class="line"><span class="cl"><span class="s">keyUsage = critical, digitalSignature, keyEncipherment
</span></span></span><span class="line"><span class="cl"><span class="s">extendedKeyUsage = serverAuth
</span></span></span><span class="line"><span class="cl"><span class="s">EOF</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA private key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -aes256 -out /etc/haproxy/ca/private/ca.key <span class="m">4096</span>
</span></span><span class="line"><span class="cl">chmod <span class="m">400</span> /etc/haproxy/ca/private/ca.key
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate CA certificate</span>
</span></span><span class="line"><span class="cl">openssl req -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/ca/private/ca.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -new -x509 -days <span class="m">3650</span> -sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions v3_ca <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/C=US/ST=State/L=City/O=MyOrg/CN=MyOrg CA&#34;</span>
</span></span></code></pre></div><h3 id="generate-server-certificate">Generate Server Certificate <a class="anchor" data-pagefind-ignore href="#generate-server-certificate" aria-label="Link to this section">#</a></h3>
<p>HAProxy presents this certificate to clients on the mTLS port. Clients verify it against the same CA, so they know they talk to the real API. The bind line loads certificate and key from one combined PEM file.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate server key</span>
</span></span><span class="line"><span class="cl">mkdir -p /etc/haproxy/certs
</span></span><span class="line"><span class="cl">openssl genrsa -out /etc/haproxy/certs/server.key <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate server CSR (clients such as Go and Python require the SAN)</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/CN=api.example.com&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -addext <span class="s2">&#34;subjectAltName=DNS:api.example.com&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign server certificate with CA</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions server_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in /etc/haproxy/ca/csr/server.csr <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM for HAProxy</span>
</span></span><span class="line"><span class="cl">cat /etc/haproxy/certs/server.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">    /etc/haproxy/certs/server.key <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; /etc/haproxy/certs/server.pem
</span></span><span class="line"><span class="cl">chmod <span class="m">600</span> /etc/haproxy/certs/server.pem
</span></span></code></pre></div><h3 id="generate-client-certificate">Generate Client Certificate <a class="anchor" data-pagefind-ignore href="#generate-client-certificate" aria-label="Link to this section">#</a></h3>
<p>Every client gets its own certificate, so you can authorize and revoke them one by one. The script takes a name (becomes the CN) and an optional OU (default <code>internal</code>); both are used in the ACLs later.</p>
<table>
	<thead>
			<tr>
					<th>Output</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>.key</code> + <code>.crt</code></td>
					<td>curl, Python, Go, Node.js</td>
			</tr>
			<tr>
					<td><code>.pem</code></td>
					<td>Tools that want certificate and key in one file</td>
			</tr>
			<tr>
					<td><code>.p12</code></td>
					<td>Browsers and Java; password <code>changeme</code>, change it</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/generate-client-cert.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_NAME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CLIENT_OU</span><span class="o">=</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">2</span><span class="k">:-</span><span class="nv">internal</span><span class="si">}</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> -z <span class="s2">&#34;</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> &lt;client-name&gt; [organizational-unit]&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">OUTPUT_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/clients/</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">mkdir -p <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client key</span>
</span></span><span class="line"><span class="cl">openssl genrsa -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="m">2048</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate client CSR</span>
</span></span><span class="line"><span class="cl">openssl req -new <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -subj <span class="s2">&#34;/OU=</span><span class="nv">$CLIENT_OU</span><span class="s2">/CN=</span><span class="nv">$CLIENT_NAME</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Sign client certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -extensions usr_cert <span class="se">\
</span></span></span><span class="line"><span class="cl">  -days <span class="m">365</span> -notext -md sha256 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/csr/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.csr&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -batch
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create combined PEM (for applications that need it)</span>
</span></span><span class="line"><span class="cl">cat <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    &gt; <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create PKCS12 bundle (for browsers and some clients)</span>
</span></span><span class="line"><span class="cl">openssl pkcs12 -export <span class="se">\
</span></span></span><span class="line"><span class="cl">  -out <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -inkey <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.key&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -in <span class="s2">&#34;</span><span class="nv">$OUTPUT_DIR</span><span class="s2">/</span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -certfile <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/certs/ca.crt&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -passout pass:changeme
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Client certificate generated in </span><span class="nv">$OUTPUT_DIR</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Files: </span><span class="nv">$CLIENT_NAME</span><span class="s2">.key, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.crt, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.pem, </span><span class="nv">$CLIENT_NAME</span><span class="s2">.p12&#34;</span>
</span></span></code></pre></div><h2 id="basic-mtls-configuration">Basic mTLS Configuration <a class="anchor" data-pagefind-ignore href="#basic-mtls-configuration" aria-label="Link to this section">#</a></h2>
<p>Two bind options switch mTLS on:</p>
<ul>
<li><code>ca-file</code>: the CA that client certificates must be signed by.</li>
<li><code>verify</code>: <code>required</code> rejects the handshake without a valid certificate; <code>optional</code> lets it through and you decide in ACLs.</li>
</ul>
<table>
	<thead>
			<tr>
					<th>Mode</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>verify required</code></td>
					<td>Endpoints only certificate holders may reach</td>
			</tr>
			<tr>
					<td><code>verify optional</code></td>
					<td>One endpoint serving both anonymous and authenticated clients</td>
			</tr>
	</tbody>
</table>
<h3 id="required-mtls">Required mTLS <a class="anchor" data-pagefind-ignore href="#required-mtls" aria-label="Link to this section">#</a></h3>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    user haproxy
    group haproxy
    daemon
    
    # SSL/TLS settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets

defaults
    log global
    mode http
    option httplog
    timeout connect 5s
    timeout client  50s
    timeout server  50s

frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate is required - connections without valid cert are rejected
    default_backend api_servers

backend api_servers
    server api1 192.168.1.10:8080 check
    server api2 192.168.1.11:8080 check
</code></pre><h3 id="optional-mtls-certificate-if-available">Optional mTLS (Certificate if Available) <a class="anchor" data-pagefind-ignore href="#optional-mtls-certificate-if-available" aria-label="Link to this section">#</a></h3>
<p>Clients with a valid certificate go to <code>authenticated_api</code>, clients without one to <code>public_api</code>, and an invalid certificate gets a 403.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_optional
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify optional
    
    # Check if client provided valid certificate
    # (ssl_c_verify is also 0 when no certificate was sent, so combine it with ssl_fc_has_crt)
    acl client_cert_valid ssl_c_verify 0
    acl client_cert_provided ssl_fc_has_crt
    
    # Reject invalid certificates
    http-request deny if client_cert_provided !client_cert_valid
    
    # Route based on certificate status
    use_backend authenticated_api if client_cert_provided client_cert_valid
    use_backend public_api unless client_cert_provided

backend authenticated_api
    server api1 192.168.1.10:8080 check

backend public_api
    server public1 192.168.1.20:8080 check
</code></pre><h2 id="passing-client-certificate-info-to-backend">Passing Client Certificate Info to Backend <a class="anchor" data-pagefind-ignore href="#passing-client-certificate-info-to-backend" aria-label="Link to this section">#</a></h2>
<p>The backend sees plain HTTP from HAProxy, not the certificate. Add headers so the application knows which client called.</p>
<h3 id="certificate-details-as-headers">Certificate Details as Headers <a class="anchor" data-pagefind-ignore href="#certificate-details-as-headers" aria-label="Link to this section">#</a></h3>
<ul>
<li><code>ssl_c_s_dn(cn)</code>: the client name, the usual identity for application logic.</li>
<li><code>ssl_c_serial</code> / <code>ssl_c_sha1</code>: unique per certificate, useful for audit logs.</li>
<li><code>%{+Q}</code>: quotes the value, since DNs contain commas and spaces.</li>
</ul>
<p><code>set-header</code> overwrites any <code>X-Client-*</code> header a client sends itself, so clients cannot fake them.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Client certificate subject (DN)
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    
    # Client certificate common name
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    
    # Certificate serial number
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    
    # Certificate fingerprint (SHA1)
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate validity dates
    http-request set-header X-Client-NotBefore %[ssl_c_notbefore]
    http-request set-header X-Client-NotAfter %[ssl_c_notafter]
    
    # Issuer DN
    http-request set-header X-Client-Issuer %{+Q}[ssl_c_i_dn]
    
    # Verification status (0 = success)
    http-request set-header X-Client-Verify %[ssl_c_verify]
    
    default_backend api_servers
</code></pre><h3 id="full-certificate-as-header-base64">Full Certificate as Header (Base64) <a class="anchor" data-pagefind-ignore href="#full-certificate-as-header-base64" aria-label="Link to this section">#</a></h3>
<p>Use this when the application must parse the certificate itself, for example to read custom extensions.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Pass entire certificate (DER format, base64 encoded)
    http-request set-header X-Client-Cert %[ssl_c_der,base64]
    
    default_backend api_servers
</code></pre><h2 id="certificate-based-authorization">Certificate-Based Authorization <a class="anchor" data-pagefind-ignore href="#certificate-based-authorization" aria-label="Link to this section">#</a></h2>
<p>A valid certificate proves who the client is, not what it may do. ACLs on certificate fields add authorization.</p>
<table>
	<thead>
			<tr>
					<th>Match on</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>CN</td>
					<td>Individual services or clients</td>
			</tr>
			<tr>
					<td>OU</td>
					<td>Groups of clients (internal, partner, admin)</td>
			</tr>
			<tr>
					<td>Fingerprint</td>
					<td>An explicit allowlist of exact certificates</td>
			</tr>
	</tbody>
</table>
<h3 id="route-by-client-cn">Route by Client CN <a class="anchor" data-pagefind-ignore href="#route-by-client-cn" aria-label="Link to this section">#</a></h3>
<p>Each named client gets its own backend; everyone else goes to <code>api_backend</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # ACLs based on client certificate CN
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_api ssl_c_s_dn(cn) -i api-client
    acl cn_monitoring ssl_c_s_dn(cn) -i monitoring
    
    # Route to different backends
    use_backend admin_backend if cn_admin
    use_backend monitoring_backend if cn_monitoring
    default_backend api_backend
</code></pre><h3 id="restrict-access-by-certificate-ou">Restrict Access by Certificate OU <a class="anchor" data-pagefind-ignore href="#restrict-access-by-certificate-ou" aria-label="Link to this section">#</a></h3>
<p>Paths are locked to a group: <code>/admin</code> only for the <code>administrators</code> OU, <code>/api/partner</code> only for <code>partner-api</code>.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Check organizational unit
    acl ou_internal ssl_c_s_dn(ou) -i internal-services
    acl ou_partner ssl_c_s_dn(ou) -i partner-api
    acl ou_admin ssl_c_s_dn(ou) -i administrators
    
    # Restrict admin endpoints
    acl admin_path path_beg /admin
    http-request deny if admin_path !ou_admin
    
    # Partner access restrictions
    acl partner_path path_beg /api/partner
    http-request deny if partner_path !ou_partner
    
    default_backend api_servers
</code></pre><h3 id="whitelist-specific-certificates">Whitelist Specific Certificates <a class="anchor" data-pagefind-ignore href="#whitelist-specific-certificates" aria-label="Link to this section">#</a></h3>
<p>The strictest option: only certificates whose SHA1 fingerprint is in the file get through, even if the CA signed others.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt verify required
    
    # Define allowed certificate fingerprints
    acl allowed_cert ssl_c_sha1,hex -f /etc/haproxy/allowed-certs.txt
    
    # Reject certificates not in whitelist
    http-request deny unless allowed_cert
    
    default_backend api_servers
</code></pre><p>Create the whitelist file. A renewed certificate has a new fingerprint, so update the file when you reissue.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># /etc/haproxy/allowed-certs.txt</span>
</span></span><span class="line"><span class="cl"><span class="c1"># One SHA1 fingerprint per line, uppercase hex without colons:</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   openssl x509 -in client.crt -noout -fingerprint -sha1 | cut -d= -f2 | tr -d :</span>
</span></span><span class="line"><span class="cl">A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0
</span></span><span class="line"><span class="cl">9T8S7R6Q5P4O3N2M1L0K9J8I7H6G5F4E3D2C1B0A
</span></span></code></pre></div><h2 id="certificate-revocation">Certificate Revocation <a class="anchor" data-pagefind-ignore href="#certificate-revocation" aria-label="Link to this section">#</a></h2>
<p>A stolen or retired client certificate stays valid until it expires. A CRL lists revoked serial numbers; HAProxy rejects them during the handshake.</p>
<h3 id="using-crl-certificate-revocation-list">Using CRL (Certificate Revocation List) <a class="anchor" data-pagefind-ignore href="#using-crl-certificate-revocation-list" aria-label="Link to this section">#</a></h3>
<p>Revoke the certificate, regenerate the CRL, then load it with <code>crl-file</code> on the bind line.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Generate initial CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Revoke a certificate</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -revoke /etc/haproxy/clients/bad-client/bad-client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config /etc/haproxy/ca/openssl.cnf <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -out /etc/haproxy/ca/crl/ca.crl
</span></span></code></pre></div><p>HAProxy reads the CRL at startup, so reload after each change.</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend mtls_api
    # HAProxy has no line continuation: keep the bind on one line
    bind *:443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required
    
    default_backend api_servers
</code></pre><h3 id="automated-crl-updates">Automated CRL Updates <a class="anchor" data-pagefind-ignore href="#automated-crl-updates" aria-label="Link to this section">#</a></h3>
<p>A CRL expires after <code>default_crl_days</code> (30). An expired CRL makes HAProxy reject every client, so regenerate it on a schedule.</p>
<p>The CA key is encrypted, and cron cannot type its passphrase. Store the passphrase in a file that only root can read, so the script can pass it to openssl with <code>-passin</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Same passphrase as the one protecting ca.key</span>
</span></span><span class="line"><span class="cl">install -m <span class="m">0400</span> /dev/null /etc/haproxy/ca/private/ca.pass
</span></span><span class="line"><span class="cl"><span class="nb">read</span> -rsp <span class="s1">&#39;CA key passphrase: &#39;</span> P <span class="o">&amp;&amp;</span> <span class="nb">printf</span> <span class="s1">&#39;%s\n&#39;</span> <span class="s2">&#34;</span><span class="nv">$P</span><span class="s2">&#34;</span> &gt; /etc/haproxy/ca/private/ca.pass<span class="p">;</span> <span class="nb">unset</span> P<span class="p">;</span> <span class="nb">echo</span>
</span></span></code></pre></div><p>Anyone with root on this machine can now sign certificates with your CA, so keep the CA host locked down.</p>
<p>The script writes to a temporary file first, so a failed run never leaves HAProxy with a broken CRL.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># /usr/local/bin/update-crl.sh</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -euo pipefail
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CA_DIR</span><span class="o">=</span><span class="s2">&#34;/etc/haproxy/ca&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CRL_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/crl/ca.crl&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">PASS_FILE</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/private/ca.pass&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Regenerate CRL; if openssl fails the script stops here and HAProxy keeps the current CRL</span>
</span></span><span class="line"><span class="cl">openssl ca -config <span class="s2">&#34;</span><span class="nv">$CA_DIR</span><span class="s2">/openssl.cnf&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -gencrl -passin <span class="s2">&#34;file:</span><span class="nv">$PASS_FILE</span><span class="s2">&#34;</span> -out <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span>
</span></span><span class="line"><span class="cl">mv <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">.new&#34;</span> <span class="s2">&#34;</span><span class="nv">$CRL_FILE</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Reload HAProxy</span>
</span></span><span class="line"><span class="cl">systemctl reload haproxy
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">chmod <span class="m">700</span> /usr/local/bin/update-crl.sh
</span></span></code></pre></div><p>Schedule with cron, in root&rsquo;s crontab (<code>crontab -e</code> as root):</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Update CRL every hour</span>
</span></span><span class="line"><span class="cl"><span class="m">0</span> * * * * /usr/local/bin/update-crl.sh
</span></span></code></pre></div><h2 id="complete-production-configuration">Complete Production Configuration <a class="anchor" data-pagefind-ignore href="#complete-production-configuration" aria-label="Link to this section">#</a></h2>
<p>Everything combined. The layout:</p>
<table>
	<thead>
			<tr>
					<th>Frontend / listen</th>
					<th>Port</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>stats</code></td>
					<td>8404</td>
					<td>Stats page and Prometheus <code>/metrics</code></td>
			</tr>
			<tr>
					<td><code>public_https</code></td>
					<td>443</td>
					<td>Public site with a public certificate; <code>/api</code> is redirected to 8443</td>
			</tr>
			<tr>
					<td><code>mtls_api</code></td>
					<td>8443</td>
					<td>mTLS with CRL, identity headers, CN/OU authorization</td>
			</tr>
	</tbody>
</table>
<p>The authorization rules in <code>mtls_api</code>:</p>
<ul>
<li><code>/api/admin</code> only for CN <code>admin-service</code>.</li>
<li>CNs containing <code>readonly</code> cannot use POST, PUT, DELETE or PATCH.</li>
<li>Only OU <code>internal</code> or <code>partner</code> gets in at all; partners go to <code>partner_api</code>.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy"># /etc/haproxy/haproxy.cfg

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    maxconn 50000
    nbthread 4
    
    # Modern TLS settings
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets
    tune.ssl.default-dh-param 2048

defaults
    log global
    mode http
    option httplog
    option dontlognull
    option forwardfor
    timeout connect 5s
    timeout client  50s
    timeout server  50s

# Stats
listen stats
    bind *:8404
    stats enable
    stats uri /stats
    stats refresh 10s
    http-request use-service prometheus-exporter if { path /metrics }

# Public HTTPS (no client cert required)
frontend public_https
    # public.pem: your publicly trusted certificate (for example Let&#39;s Encrypt), not one from the internal CA
    bind *:443 ssl crt /etc/haproxy/certs/public.pem alpn h2,http/1.1
    
    # Route to mTLS frontend for API paths
    acl api_path path_beg /api
    use_backend mtls_redirect if api_path
    
    default_backend public_web

# mTLS API endpoint
frontend mtls_api
    bind *:8443 ssl crt /etc/haproxy/certs/server.pem ca-file /etc/haproxy/ca/certs/ca.crt crl-file /etc/haproxy/ca/crl/ca.crl verify required alpn h2,http/1.1
    
    # Log client certificate info
    capture request header X-Client-CN len 50
    log-format &#34;%ci:%cp [%tr] %ft %b/%s %ST %B %TR/%Tw/%Tc/%Tr/%Ta client_cn:%{+Q}[ssl_c_s_dn(cn)] %r&#34;
    
    # Add client info headers
    http-request set-header X-Client-CN %{+Q}[ssl_c_s_dn(cn)]
    http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn]
    http-request set-header X-Client-Serial %[ssl_c_serial,hex]
    http-request set-header X-Client-Verify %[ssl_c_verify]
    http-request set-header X-Client-Fingerprint %[ssl_c_sha1,hex]
    
    # Certificate-based authorization
    acl cn_admin ssl_c_s_dn(cn) -i admin-service
    acl cn_readonly ssl_c_s_dn(cn) -m sub readonly
    acl ou_internal ssl_c_s_dn(ou) -i internal
    acl ou_partner ssl_c_s_dn(ou) -i partner
    
    # Path-based ACLs
    acl admin_path path_beg /api/admin
    acl write_method method POST PUT DELETE PATCH
    
    # Authorization rules
    http-request deny if admin_path !cn_admin
    http-request deny if write_method cn_readonly
    http-request deny if !ou_internal !ou_partner
    
    # Route based on certificate
    use_backend admin_api if cn_admin
    use_backend partner_api if ou_partner
    default_backend internal_api

# Redirect to mTLS port
backend mtls_redirect
    http-request redirect code 301 location https://%[req.hdr(Host)]:8443%[capture.req.uri]

backend public_web
    balance roundrobin
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check

backend internal_api
    balance leastconn
    option httpchk GET /health
    http-check expect status 200
    server api1 192.168.1.20:8080 check
    server api2 192.168.1.21:8080 check

backend admin_api
    option httpchk GET /health
    server admin1 192.168.1.30:8080 check

backend partner_api
    balance roundrobin
    option httpchk GET /health
    server partner1 192.168.1.40:8080 check
    server partner2 192.168.1.41:8080 check
</code></pre><h2 id="testing-mtls">Testing mTLS <a class="anchor" data-pagefind-ignore href="#testing-mtls" aria-label="Link to this section">#</a></h2>
<p>Test both sides: a request with a certificate must work, one without must fail.</p>
<h3 id="test-with-curl">Test with curl <a class="anchor" data-pagefind-ignore href="#test-with-curl" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test with client certificate</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  --key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test with combined PEM</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cert /etc/haproxy/clients/api-client/api-client.pem <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test without certificate (should fail)</span>
</span></span><span class="line"><span class="cl">curl -v <span class="se">\
</span></span></span><span class="line"><span class="cl">  --cacert /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  https://api.example.com:8443/api/status
</span></span></code></pre></div><h3 id="test-with-openssl">Test with openssl <a class="anchor" data-pagefind-ignore href="#test-with-openssl" aria-label="Link to this section">#</a></h3>
<p><code>s_client</code> shows the handshake: the server certificate, whether HAProxy asked for a client certificate, and the verify result.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Connect and show certificate exchange</span>
</span></span><span class="line"><span class="cl">openssl s_client <span class="se">\
</span></span></span><span class="line"><span class="cl">  -connect api.example.com:8443 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -cert /etc/haproxy/clients/api-client/api-client.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -key /etc/haproxy/clients/api-client/api-client.key <span class="se">\
</span></span></span><span class="line"><span class="cl">  -CAfile /etc/haproxy/ca/certs/ca.crt <span class="se">\
</span></span></span><span class="line"><span class="cl">  -verify_return_error
</span></span></code></pre></div><h2 id="client-configuration-examples">Client Configuration Examples <a class="anchor" data-pagefind-ignore href="#client-configuration-examples" aria-label="Link to this section">#</a></h2>
<p>Every client needs the same three files: its certificate, its key, and the CA certificate to verify HAProxy.</p>
<h3 id="python-requests">Python requests <a class="anchor" data-pagefind-ignore href="#python-requests" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">response</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="s1">&#39;https://api.example.com:8443/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">,</span> <span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">    <span class="n">verify</span><span class="o">=</span><span class="s1">&#39;/path/to/ca.crt&#39;</span>
</span></span><span class="line"><span class="cl"><span class="p">)</span>
</span></span></code></pre></div><h3 id="nodejs">Node.js <a class="anchor" data-pagefind-ignore href="#nodejs" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-javascript" data-lang="javascript"><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">https</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;https&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">fs</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;fs&#39;</span><span class="p">);</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">options</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hostname</span><span class="o">:</span> <span class="s1">&#39;api.example.com&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">port</span><span class="o">:</span> <span class="mi">8443</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">path</span><span class="o">:</span> <span class="s1">&#39;/api/data&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">method</span><span class="o">:</span> <span class="s1">&#39;GET&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nx">cert</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.crt&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">key</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/client.key&#39;</span><span class="p">),</span>
</span></span><span class="line"><span class="cl">  <span class="nx">ca</span><span class="o">:</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="s1">&#39;/path/to/ca.crt&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="p">};</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">const</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">https</span><span class="p">.</span><span class="nx">request</span><span class="p">(</span><span class="nx">options</span><span class="p">,</span> <span class="p">(</span><span class="nx">res</span><span class="p">)</span> <span class="p">=&gt;</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="c1">// Handle response
</span></span></span><span class="line"><span class="cl"><span class="p">});</span>
</span></span></code></pre></div><h3 id="go">Go <a class="anchor" data-pagefind-ignore href="#go" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go"><span class="line"><span class="cl"><span class="kn">package</span><span class="w"> </span><span class="nx">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kn">import</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/tls&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;crypto/x509&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;io/ioutil&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="s">&#34;net/http&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="kd">func</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">cert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">tls</span><span class="p">.</span><span class="nf">LoadX509KeyPair</span><span class="p">(</span><span class="s">&#34;client.crt&#34;</span><span class="p">,</span><span class="w"> </span><span class="s">&#34;client.key&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCert</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">ioutil</span><span class="p">.</span><span class="nf">ReadFile</span><span class="p">(</span><span class="s">&#34;ca.crt&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">x509</span><span class="p">.</span><span class="nf">NewCertPool</span><span class="p">()</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">caCertPool</span><span class="p">.</span><span class="nf">AppendCertsFromPEM</span><span class="p">(</span><span class="nx">caCert</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">client</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Client</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nx">Transport</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">http</span><span class="p">.</span><span class="nx">Transport</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nx">TLSClientConfig</span><span class="p">:</span><span class="w"> </span><span class="o">&amp;</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Config</span><span class="p">{</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">Certificates</span><span class="p">:</span><span class="w"> </span><span class="p">[]</span><span class="nx">tls</span><span class="p">.</span><span class="nx">Certificate</span><span class="p">{</span><span class="nx">cert</span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">                </span><span class="nx">RootCAs</span><span class="p">:</span><span class="w">      </span><span class="nx">caCertPool</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="p">},</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="p">}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nx">resp</span><span class="p">,</span><span class="w"> </span><span class="nx">_</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">client</span><span class="p">.</span><span class="nf">Get</span><span class="p">(</span><span class="s">&#34;https://api.example.com:8443/api/data&#34;</span><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c1">// Handle response</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">}</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="common-errors">Common Errors <a class="anchor" data-pagefind-ignore href="#common-errors" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Error</th>
					<th>Cause</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>tlsv1 alert unknown ca</code></td>
					<td>Client certificate not signed by the CA in <code>ca-file</code></td>
			</tr>
			<tr>
					<td><code>SSL certificate verify failed</code></td>
					<td>CA certificate mismatch</td>
			</tr>
			<tr>
					<td><code>tlsv13 alert certificate required</code> (TLS 1.2: handshake failure)</td>
					<td>Client didn&rsquo;t provide certificate when required</td>
			</tr>
			<tr>
					<td><code>ssl/tls alert certificate revoked</code></td>
					<td>Certificate is in CRL</td>
			</tr>
	</tbody>
</table>
<h3 id="debug-commands">Debug Commands <a class="anchor" data-pagefind-ignore href="#debug-commands" aria-label="Link to this section">#</a></h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Verify certificate chain</span>
</span></span><span class="line"><span class="cl">openssl verify -CAfile ca.crt client.crt
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check certificate details</span>
</span></span><span class="line"><span class="cl">openssl x509 -in client.crt -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check CRL contents</span>
</span></span><span class="line"><span class="cl">openssl crl -in ca.crl -text -noout
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test SSL connection with debug</span>
</span></span><span class="line"><span class="cl">openssl s_client -connect api.example.com:8443 -debug
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Protect the CA key.</strong> Whoever has it can mint valid client certificates. Keep it encrypted and the CA host locked down.</li>
<li><strong>Short client lifetimes.</strong> 365 days here; shorter limits the damage of a leaked key.</li>
<li><strong>Keep the CRL fresh.</strong> Run the hourly update; an expired CRL locks everyone out.</li>
<li><strong>Do not trust client headers.</strong> Always overwrite <code>X-Client-*</code> in HAProxy, as above, and make backends reachable only through HAProxy.</li>
<li><strong>Change the PKCS12 password</strong> from <code>changeme</code> in the client script.</li>
</ul>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-mtls" rel="noopener">pderuiter/blog-haproxy-mtls</a>. It creates an HAProxy VM on Proxmox, builds the internal CA with server and client certificates, and configures the complete production configuration from this post with certificate-based authorization and the hourly CRL update; put the CA passphrase in <code>vault.yml</code>, run <code>terraform apply</code>, then <code>ansible-playbook site.yml</code>.</p>
<h2 id="next-steps">Next Steps <a class="anchor" data-pagefind-ignore href="#next-steps" aria-label="Link to this section">#</a></h2>
<p>Next in the series: the HAProxy Data Plane API for dynamic configuration management.</p>
<h2 id="summary">Summary <a class="anchor" data-pagefind-ignore href="#summary" aria-label="Link to this section">#</a></h2>
<p>Key points for HAProxy mTLS:</p>
<ul>
<li>Use <code>verify required</code> for mandatory client certificates</li>
<li>Use <code>verify optional</code> for mixed authentication</li>
<li>Pass certificate details to backends via headers</li>
<li>Implement authorization based on CN, OU, or fingerprint</li>
<li>Maintain CRL for certificate revocation</li>
<li>Generate unique certificates for each client/service</li>
<li>Test thoroughly with curl and openssl</li>
</ul>
<p>mTLS gives strong mutual authentication without passwords, a good fit for service-to-service communication and API access.</p>
]]></content:encoded></item></channel></rss>