mTLS client side certificate authentication

In mTLS, both the client and server have a certificate, and both sides authenticate using their public/private key pair. A "root" TLS certificate is necessary for mTLS; this enables an organization to be their own certificate authority. The certificates used by authorized clients and servers have to correspond to this root certificate. The root certificate is self-signed, meaning that the organization creates it themselves.

To enable mTLS client side certificate authentication we need to generate a "root" Certificate Authority (CA) and a public/private key pair. These generated files should be made available in the /etc/nginx/certs/ for nginx-proxy to activate mTLS Client Side certificate verification. Make sure you rename the file according your configuration.

In this example we use the easy-rsa tool. There are prebuild releases available but in this tutorial we will use docker images created by theohbrothers/docker-easyrsa.

easy-rsa is a CLI utility to build and manage a PKI CA. In layman's terms, this means to create a root certificate authority, and request and sign certificates, including intermediate CAs and certificate revocation lists (CRL).

All commands specify a bind mount volume ./data so make sure you run all this commands from the folder where you want to store the easyrsa output files. Make sure you backup this folder and files as that contains your PKI with CA and keypairs.

1. Create (initialize) a new PKI:

   • docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest init-pki
   • This will create a new, blank PKI structure ready to be used. Once created, this PKI can be used to make a new CA or generate keypairs.

2. Generate a Certificate Authority (CA):

   • docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest build-ca nopass
   • Enter the Common Name you want to use.
   • Your CA file will be written to: /data/pki/ca.crt
   • You can use this CA file in the Per-VIRTUAL_HOST or Global configuration.

3. Generate the client public/private key pair:

   • docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest build-client-full Bob nopass
   • Adjust the Bob in the command to match your prefered CN. You should create a unique keypair for each client/user.
   • Type the word 'yes' to continue.
   • By default easyrsa will use a validity date of 825 days. If you want to change this add -e EASYRSA_CERT_EXPIRE=3650 in the command (3650 = 10 years).
   • Your "Bob" Client certificate and private key will be written to: /data/pki/issued/Bob.crt and /data/pki/private/Bob.key
   • In Curl you can use these files to authenticate.
   • In Windows if you want to import in your certificate store you have to generate the keypair in PKCS#12 format: docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest export-p12 Bob
   • Your "Bob" PKCS#12 archive file will be written to: /data/pki/private/Bob.p12
   • You can import this .p12 in the Windows certificate store or in your browser.

4. Create the Certificate Revocation List (CRL):

   • docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest gen-crl
   • Your CRL file will be written to: /data/pki/crl.pem
   • You can use this CRL file according the Certificate Revocation List (CRL) documentation.

To make an existing certificate invalid (revoke) use this command:

1. docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest revoke Name co

   • Adjust the Name and Reason (co) in the command to match your certificate which you want to revoke.
     • co is the Reason for revoking (cessationOfOperation) and can be as follows:
     • us | uns* | unspecified
     • kc | key* | keyCompromise
     • cc | ca* | CACompromise
     • ac | aff* | affiliationChanged
     • ss | sup* | superseded
     • co | ces* | cessationOfOperation
     • ch | cer* | certificateHold

2. Re-generate the Certificate Revocation List (CRL):

   • docker run --rm -it -v ./data:/data theohbrothers/docker-easyrsa:latest gen-crl
   • By default easyrsa will use a expire date of 180 days. Which means you have to recreate and republish the CRL file even if it's not changed, otherwise connections are not accepted. If you want to change the validity date add -e EASYRSA_CRL_DAYS=3650 in the command (3650 = 10 years). You can parse the CRL for debugging purposes in the pkitools.net CSR Reader.
   • Update this file in your nginx-proxy container so nginx is aware of the new revoked certificate and clients trying to use a revoked keypair are rejected.