Client certificate authentication

Client certificate authentication means that the client sends an X.509 certificate when they connect over TLS. The load balancer verifies the client’s identity based on the certificate. Typically, client certificates are digitally signed with your organization’s CA certificate. When a client presents one, you can verify whether it was indeed signed by your CA. If not, deny the request. You would give a unique certificate to each client to which you want to grant access.

Create a Certificate Authority Jump to heading

Creating a client certificate that’s signed by your organization’s self-signed CA (Certificate Authority) is deemed secure in this scenario, as opposed to procuring one from an external CA. Your organization acts as the Certificate Authority, authenticating these certificates when they are presented through HTTPS requests by clients.

Creating a Certificate Authority involves generating a CA key pair, creating a self-signed CA certificate, and configuring the CA to sign other certificates. You can accomplish it all with a single openssl command.

Generate a CA key pair and self-signed certificate:

nix
openssl req \
  -newkey rsa:2048 \
  -nodes \
  -x509 \
  -days 3650 \
  -keyout privateCA.pem \
  -out ca.crt

nix
openssl req \
  -newkey rsa:2048 \
  -nodes \
  -x509 \
  -days 3650 \
  -keyout privateCA.pem \
  -out ca.crt

Learn more about this command

The options of this command break down as follows:

openssl req creates and processes certificate signing requests (CSRs) and certificates.
-newkey rsa:2048 specifies the generation of a new RSA key pair with a key size of 2048 bits.
-nodes indicates that the private key should not be encrypted with a passphrase and will be saved in an unencrypted format.
-x509 tells OpenSSL to generate a self-signed certificate instead of a CSR.
-days 3650 specifies the validity period of the certificate as 3650 days (approximately 10 years).
-keyout designates the file name of privateCA.pem for the private key.
-out ca.crt sets the certificate.

The command will also prompt you to enter information for the certificate, such as the Common Name (CN), organization details, and so on. Fill in the required fields accordingly.

nix
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

nix
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

To display the details of the CA certificate and verify its information, use the openssl x509 command:
```
nix
openssl x509 -in ca.crt -text -noout
```
```
nix
openssl x509 -in ca.crt -text -noout
```
After following these steps, you should have the self-signed certificate ca.crt. Remember to adjust the file names and paths according to your specific setup. Keep the CA key privateCA.pem secret.

Create a client certificate Jump to heading

A client certificate is a type of digital certificate used to verify the identity of a user or device trying to access server resources.

To create a client certificate:

Create a certificate signing request with the following command, replacing the -subj values with the name and organization of the user or device:

nix
openssl req \
  -newkey rsa:2048 \
  -nodes \
  -days 3650 \
  -subj "/CN=exampleUser/O=exampleOrganization" \
  -keyout clientKey.pem \
  -out client.csr

nix
openssl req \
  -newkey rsa:2048 \
  -nodes \
  -days 3650 \
  -subj "/CN=exampleUser/O=exampleOrganization" \
  -keyout clientKey.pem \
  -out client.csr

Create a certificate extensions file named client-cert-extensions.cnf, which sets extensions fields like basicConstraints to prevent the certificate from acting as a CA and keyUsage to indicate the purpose of the certificate. Add the following values:

client-cert-extensions.cnf
text
basicConstraints = CA:FALSE
keyUsage = digitalSignature
extendedKeyUsage = clientAuth
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer

client-cert-extensions.cnf
text
basicConstraints = CA:FALSE
keyUsage = digitalSignature
extendedKeyUsage = clientAuth
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer

Use the following command to sign the certificate signing request. This uses our previously generated CSR client.csr, CA certificate ca.crt, and CA key privateCA.pem to create a client certificate, client.crt.

nix
openssl x509 \
  -req \
  -in client.csr \
  -out client.crt \
  -CA ca.crt \
  -CAkey privateCA.pem \
  -CAcreateserial \
  -days 3650 \
  -extfile client-cert-extensions.cnf

nix
openssl x509 \
  -req \
  -in client.csr \
  -out client.crt \
  -CA ca.crt \
  -CAkey privateCA.pem \
  -CAcreateserial \
  -days 3650 \
  -extfile client-cert-extensions.cnf

Successful confirmation output will look something like this, with an ‘OK’ statement above your Common Name and Organization:

output
text
Certificate request self-signature ok
subject=CN = exampleUser, O = exampleOrganization

output
text
Certificate request self-signature ok
subject=CN = exampleUser, O = exampleOrganization

Your client certificate is now ready to use.

To display the details of the client certificate and verify its information, use the openssl x509 command:
```
nix
openssl x509 -in client.crt -text -noout
```
```
nix
openssl x509 -in client.crt -text -noout
```

Verify client certificates Jump to heading

In your load balancer configuration, enable verification of client certificates by setting verify to required on a bind line. The ca-file parameter specifies the CA file to use to verify:

haproxy
frontend www
  bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt

haproxy
frontend www
  bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt

Note that the certificate provided by the client must contain both the public certificate and its associated private key.

Send a client certificate to servers Jump to heading

The load balancer can also send its own client certificate to backend servers. The servers would then be responsible for verifying it.

In the backend, add the crt argument to the server directive. The crt parameter points to your load balancer’s client certificate file:

haproxy
backend webservers
  server web1 10.0.0.5:443 ssl crt /certs/load-balancer-client.crt

haproxy
backend webservers
  server web1 10.0.0.5:443 ssl crt /certs/load-balancer-client.crt

Certificate Revocation Lists Jump to heading

A Certificate Revocation List (CRL) contains a list of the certificates that have been revoked.

Create a CRL Jump to heading

To create a CRL:

Create the directory structure and necessary files. You can choose different directory paths, however ensure all created files are in the proper locations:

nix
mkdir -p ./databaseCA/certs ./databaseCA/private ./databaseCA/crl
touch ./databaseCA/index.txt ./databaseCA/serial ./databaseCA/crlnumber
echo 01 > ./databaseCA/serial
echo 1000 > ./databaseCA/crlnumber

nix
mkdir -p ./databaseCA/certs ./databaseCA/private ./databaseCA/crl
touch ./databaseCA/index.txt ./databaseCA/serial ./databaseCA/crlnumber
echo 01 > ./databaseCA/serial
echo 1000 > ./databaseCA/crlnumber

Copy your CA certificate and private key into the databaseCA directory.

nix
cp ca.crt ./databaseCA
cp privateCA.pem ./databaseCA

nix
cp ca.crt ./databaseCA
cp privateCA.pem ./databaseCA

You’ll need a configuration file for OpenSSL. An example file named openssl.cnf can usually be found in the directories /usr/lib/ssl/ or /etc/ssl/. Copy this to the current directory. Below is an example snippet from the file, modified for the certificates we created:

openssl.cnf
ini
# OpenSSL example configuration file.
# See doc/man5/config.pod for more info.
####################################################################
[ ca ]
default_ca       = CA_default        # The default ca section
####################################################################
[ CA_default ]
dir              = ./databaseCA       # Where everything is kept
certs            = $dir/certs         # Where the issued certs are kept
crl_dir          = $dir/crl           # Where the issued crl are kept
database         = $dir/index.txt     # database index file.
new_certs_dir    = $dir/newcerts      # default place for new certs.
certificate      = $dir/ca.crt        # The CA certificate
serial           = $dir/serial        # The current serial number
crlnumber        = $dir/crlnumber     # the current crl number
crl              = $dir/crl.pem       # The current CRL
private_key      = $dir/privateCA.pem # The private key
x509_extensions  = usr_cert           # The extensions to add to the cert
crl_extensions   = crl_ext
default_days     = 3650               # how long to certify for
default_crl_days = 30                 # how long before next CRL
default_md       = sha256             # use SHA-256 by default
preserve         = no                 # keep passed DN ordering
[ crl_ext ]
authorityKeyIdentifier=keyid:always

openssl.cnf
ini
# OpenSSL example configuration file.
# See doc/man5/config.pod for more info.
####################################################################
[ ca ]
default_ca       = CA_default        # The default ca section
####################################################################
[ CA_default ]
dir              = ./databaseCA       # Where everything is kept
certs            = $dir/certs         # Where the issued certs are kept
crl_dir          = $dir/crl           # Where the issued crl are kept
database         = $dir/index.txt     # database index file.
new_certs_dir    = $dir/newcerts      # default place for new certs.
certificate      = $dir/ca.crt        # The CA certificate
serial           = $dir/serial        # The current serial number
crlnumber        = $dir/crlnumber     # the current crl number
crl              = $dir/crl.pem       # The current CRL
private_key      = $dir/privateCA.pem # The private key
x509_extensions  = usr_cert           # The extensions to add to the cert
crl_extensions   = crl_ext
default_days     = 3650               # how long to certify for
default_crl_days = 30                 # how long before next CRL
default_md       = sha256             # use SHA-256 by default
preserve         = no                 # keep passed DN ordering
[ crl_ext ]
authorityKeyIdentifier=keyid:always

The above is just the CA_default portion of a default OpenSSL configuration, not the entire openssl.cnf file.

In this configuration, ./databaseCA is the directory where OpenSSL will store its database of certificates, ./privateCA.pem is the CA’s private key, and ./ca.crt is the CA’s certificate.

Ensure the directory and file paths match your environment, which we created in Step 1.
Consult the openssl ca documentation for a complete list of configuration options.

Generate the file revoked.crl, which will contain the list of revoked certificates:
```
nix
sudo openssl ca -config openssl.cnf -gencrl -out /certs/revoked.crl
```
```
nix
sudo openssl ca -config openssl.cnf -gencrl -out /certs/revoked.crl
```
You can create a CRL file even before a certificate has been revoked; the revocation list will be empty inside the CRL.

Configure the load balancer Jump to heading

By using Certificate Revocation Lists, you can revoke client certificates in your load balancer environment. Revoked certificates will be denied access based on your configured CRL file.

Here is an example snippet in which we add the crl-file argument to deny access to clients who have revoked certificates:

haproxy
frontend www
   mode http
   bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt crl-file /certs/revoked.crl

haproxy
frontend www
   mode http
   bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt crl-file /certs/revoked.crl

Revoke a certificate Jump to heading

To revoke a client certificate:

Invoke the openssl ca command with the -revoke argument:

nix
sudo openssl ca -config openssl.cnf -revoke client.crt

nix
sudo openssl ca -config openssl.cnf -revoke client.crt

This will immediately revoke the certificate client.crt as confirmed by the output:

output
text
Using configuration from openssl.cnf
Revoking Certificate 01.
Data Base Updated

output
text
Using configuration from openssl.cnf
Revoking Certificate 01.
Data Base Updated

Update the CRL file:

nix
sudo openssl ca -config openssl.cnf -gencrl -out /certs/revoked.crl

nix
sudo openssl ca -config openssl.cnf -gencrl -out /certs/revoked.crl

Reload the load balancer configuration.

Show error pages for certificate errors Jump to heading

By utilizing the configuration options below, you can show users an error page based on a certificate error.

Configure HTML pages on your load balancer, for example certexpired.html and certrevoked.html pages.
- The file /certexpired.html could present a dedicated page to users whose certificate has expired, providing guidance on how to renew or request a new certificate.
- Those with revoked certificates could be directed to the dedicated page /certrevoked.html.

Edit your load balancer configuration to include http-request return directives. Also, add the crt-ignore-err argument to the bind line so that errors don’t immediately close the connection, allowing you to return a web page instead:

haproxy
frontend www
   mode http
   bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt crl-file /certs/revoked.crl crt-ignore-err 10,23
   http-request return status 403 content-type text/html file /certexpired.html if { ssl_c_verify 10 }
   http-request return status 403 content-type text/html file /certrevoked.html if { ssl_c_verify 23 }

haproxy
frontend www
   mode http
   bind :443 ssl crt /certs/site.pem verify required ca-file /certs/ca.crt crl-file /certs/revoked.crl crt-ignore-err 10,23
   http-request return status 403 content-type text/html file /certexpired.html if { ssl_c_verify 10 }
   http-request return status 403 content-type text/html file /certrevoked.html if { ssl_c_verify 23 }

Reload the load balancer configuration.

Product Documentation

API Documentation

Configuration Documentation

Client certificate authentication

Create a Certificate Authority Jump to heading

Create a client certificate Jump to heading

Verify client certificates Jump to heading

Send a client certificate to servers Jump to heading

Certificate Revocation Lists Jump to heading

Create a CRL Jump to heading

Configure the load balancer Jump to heading

Revoke a certificate Jump to heading

Show error pages for certificate errors Jump to heading

See also Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Create a Certificate Authority Jump to heading #

Create a client certificate Jump to heading #

Verify client certificates Jump to heading #

Send a client certificate to servers Jump to heading #

Certificate Revocation Lists Jump to heading #

Create a CRL Jump to heading #

Configure the load balancer Jump to heading #

Revoke a certificate Jump to heading #

Show error pages for certificate errors Jump to heading #

See also Jump to heading #

Privacy Settings

Create a Certificate Authority Jump to heading

Create a client certificate Jump to heading

Verify client certificates Jump to heading

Send a client certificate to servers Jump to heading

Certificate Revocation Lists Jump to heading

Create a CRL Jump to heading

Configure the load balancer Jump to heading

Revoke a certificate Jump to heading

Show error pages for certificate errors Jump to heading

See also Jump to heading