Skip to main content Logo

Quis custodiet ipsos custodes?
Home | About | All pages | Cluster Status | RSS Feed | Gopher

haproxy: client side ssl certificates

Published: 18-12-2013 | Author: Remy van Elst | Text only version of this article

❗ This post is over eight years old. It may no longer be up to date. Opinions may have changed.

Table of Contents

This tutorial shows you how to configure haproxy and client side ssl certificates.

You need at least haproxy 1.5 dev 16 for this to work. If you want to pass the full sha 1 hash of a certificate to a backend you need at least 1.5 dev 19.

I'm developing a desktop monitoring app, Leaf Node Monitoring, open source, but paid. For Windows, Linux & Android, go check it out.

Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.

You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $100 credit for 60 days.

Place the certificate chain file somewhere haproxy can access it and append the following to your bind config line in the frontends where you want to use client side certificates: ca-file <path to certificate chain> verify required. If you want to also accept visitors without an ssl certificate change verify required to verify optional. You might want this if you handle the certificates in your application.

Below is an example which sends users to a different backend based on if there is a client side certificate. It also sends users to a special error page if there are validation errors with their client side certificate.

frontend intranet
    mode http
    bind ssl crt /etc/haproxy/pem/server.pem ca-file /etc/haproxy/pem/client-chain.pem verify optional crt-ignore-err all crl-file /etc/haproxy/crl/haproxy.pem
    use_backend ssl-error unless { ssl_c_verify 0 }
    use_backend wiki if { ssl_fc_has_crt }
    default_backend helpdesk

backend wiki
    mode http
    server wiki1 check
    server wiki2 check

backend ssl-error
    mode http
    server helpdesk1 check
    server helpdesk2 check

backend expired
    mode http
    option http-server-close
    redirect location /certificate-expired.html if { ssl_c_verify 10 } ! { path /certificate-expired.html }
    redirect location /certificate-revoked.html if { ssl_c_verify 23 } ! { path /certificate-revoked.html }
    redirect location /other-certificate-error.html unless { ssl_c_verify 0 } ! { path //other-certificate-error.html }
    server helpdesk3 check

Note that this example config also uses a CRL file to check for revocations. You need to place that CRL file.

I've had issues with a DER encoded CRL file for haproxy. To convert it to pem you can use the following command:

openssl crl -in example.crl -inform DER -outform PEM -out /etc/haproxy/crl/haproxy.crl

Combine this with a cronjob that downloads the CRL you are good to go:

*/5 * * * * wget -O /tmp/haproxy.crl && openssl crl -in /tmp/example.crl -inform DER -outform PEM -out /etc/haproxy/crl/haproxy.crl

Sending certificate details to backend application

You can also send specific details about a client certificate to your backend application. You can then handle the verification of the certificate in your backend application.

This example config sends all available certificate details to your backend application as HTTP Headers:

frontend intranet
    bind ssl crt /etc/haproxy/pem/server.pem ca-file /etc/haproxy/pem/client-chain.pem verify required
    http-request set-header X-SSL                       %[ssl_fc]
    http-request set-header X-SSL-Client-Verify         %[ssl_c_verify]
    http-request set-header X-SSL-Client-SHA1           %{+Q}[ssl_c_sha1]
    http-request set-header X-SSL-Client-DN             %{+Q}[ssl_c_s_dn]
    http-request set-header X-SSL-Client-CN             %{+Q}[ssl_c_s_dn(cn)]
    http-request set-header X-SSL-Issuer                %{+Q}[ssl_c_i_dn]
    http-request set-header X-SSL-Client-Not-Before     %{+Q}[ssl_c_notbefore]
    http-request set-header X-SSL-Client-Not-After      %{+Q}[ssl_c_notafter]
    default_backend example_backend

The {+Q} means that the data is quoted as a string. Otherwise it would be binary or boolean.

In your backend the headers look like this:

X-SSL: 1
# 1 if client used a secure connection, 0 if not.

X-SSL-Client-Verify: 0
# The status code of the SSL client connection

X-SSL-Client-SHA1: "a01b894d12579d88efce97d27107f380b05f5968"
# The SHA 1 hash of the client certificate.

X-SSL-Client-DN: "/C=NL/ST=Zuid Holland/L=Rotterdam/O=Sparkling Network/CN=exampleUserCertificate/"
# The full Distinguished Name of the client certificate.

X-SSL-Client-CN: "exampleUserCertificate"
# The full Common Name of the client certificate.

X-SSL-Issuer: "/C=NL/ST=Zuid Holland/L=Rotterdam/O=Sparkling Network/CN=Sparkling Intermediate Client SSL CA 2"
# The full Distinguished Name of the issuing certificate.

X-SSL-Client-Not-Before: "120101100030Z"
# Date from on which certificate is valid in format: YYMMDDhhmmss

X-SSL-Client-Not-After: "160101100030Z"
# Date from on which certificate is not valid anymore in format: YYMMDDhhmmss

Testing it

You can use OpenSSL to test client side certificate authentication:

openssl s_client -connect -cert ./client.pem -key ./client.key


Tags: apache , client-side-ssl , haproxy , loadbalancer , ssl , tutorials