Raymii.org

Table of Contents

• Sending certificate details to backend application
• Testing it
• Links

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.

Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below:

I'm developing an open source monitoring app called Leaf Node Monitoring, 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 $200 credit for 60 days. Spend $25 after your credit expires and I'll get $25!

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 10.20.30.40:443 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 10.20.10.10:80 check
    server wiki2 10.20.10.20:80 check

backend ssl-error
    mode http
    server helpdesk1 10.20.20.10:80 check
    server helpdesk2 10.20.20.20:80 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 10.20.20.30:80 check

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

• If the client did not provide a certificate, haproxy uses the helpdesk backend.
• If the client provides a certificate, haproxy uses the wiki backend
• If there is an error with the client certificate, haproxy uses the ssl-error backend.
  • If the certificate is revoked, haproxy redirects the user to the certificate-revoked.html page on that backend server.
  • If the certificate is expired, haproxy redirects the user to the certificate-expired.html page on that backend server.
  • If there is any other error, haproxy redirects the user to the other-certificate-error.html page on that backend server.

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 http://example-ca.org/crl/example_crl.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 10.20.30.40:443 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/emailAddress=example@example.org"
# 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 10.20.30.40:443 -cert ./client.pem -key ./client.key

Links

• OpenSSL CRL
• haproxy 1.5 ssl certificate data

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