mTLS: secure a service with nginx
Make both sides prove who they are. Configure nginx to require client certificates and test with curl.
In normal TLS only the server shows a certificate. With mutual TLS (mTLS) the client shows one too. The server refuses anyone whose certificate wasn’t issued by a CA it trusts. It’s a strong way to lock down APIs, internal services and device traffic.
You need the CA from module 2 running before you start. Work in a new folder:
mkdir -p ~/pki-lab/mtls && cd ~/pki-lab/mtls1. Issue a server certificate
Section titled “1. Issue a server certificate”Request a certificate for localhost. Enter the provisioner password when asked.
step ca certificate localhost server.crt server.key✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]✔ CA: https://localhost:9000✔ Certificate: server.crt✔ Private Key: server.key2. Issue a client certificate
Section titled “2. Issue a client certificate”step ca certificate alice client.crt client.key✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]✔ CA: https://localhost:9000✔ Certificate: client.crt✔ Private Key: client.keyThe default template gives every certificate both Server and Client Authentication, so this one works for mTLS as-is. Module 5 shows how to make them stricter.
3. Copy the files for nginx
Section titled “3. Copy the files for nginx”Copy the root certificate into your working folder:
cp $(step path)/certs/root_ca.crt .Create a folder for nginx to read from:
sudo mkdir -p /etc/pki-labCopy the server certificate, server key and root into it:
sudo cp server.crt server.key root_ca.crt /etc/pki-lab/4. Configure nginx
Section titled “4. Configure nginx”server { listen 8443 ssl; server_name localhost;
ssl_certificate /etc/pki-lab/server.crt; ssl_certificate_key /etc/pki-lab/server.key;
# Trust only client certs from our CA ssl_client_certificate /etc/pki-lab/root_ca.crt; ssl_verify_client on; ssl_verify_depth 2;
location / { return 200 "Hello, $ssl_client_s_dn\n"; }}Check the config:
sudo nginx -tnginx: the configuration file /etc/nginx/nginx.conf syntax is oknginx: configuration file /etc/nginx/nginx.conf test is successfulReload nginx to apply the config:
sudo nginx -s reloadOn macOS with Homebrew, the config folder is $(brew --prefix)/etc/nginx/servers/ and you don’t need sudo.
5. Test it
Section titled “5. Test it”Without a client certificate, nginx rejects you:
curl --cacert root_ca.crt https://localhost:8443<html><head><title>400 No required SSL certificate was sent</title></head>With one, you’re in:
curl --cacert root_ca.crt \ --cert client.crt --key client.key \ https://localhost:8443Hello, CN=alice$ssl_client_s_dn is the client certificate’s subject. A real app uses it, or the SAN, to decide what this client may do.
Break it
Section titled “Break it”A client certificate with no intermediate
Section titled “A client certificate with no intermediate”Make a copy of the client certificate with only the leaf:
awk '/BEGIN/{n++} n==1' client.crt > client-leaf.crtcurl --cacert root_ca.crt \ --cert client-leaf.crt --key client.key \ https://localhost:8443<html><head><title>400 The SSL certificate error</title></head>nginx has only the root. Without the intermediate, it can’t build the chain. This proves the tip above: the client must send the bundle.
A client certificate from another CA
Section titled “A client certificate from another CA”Any certificate from a CA that nginx doesn’t trust gets the same answer. If you made a second test CA, issue a client certificate from it as other.crt and other.key, then try it:
curl --cacert root_ca.crt \ --cert other.crt --key other.key \ https://localhost:8443<html><head><title>400 The SSL certificate error</title></head>To see the exact reason, raise the log level. Add error_log /var/log/nginx/error.log info; inside the server block and reload. Repeat both tests, then read the log:
sudo grep "client SSL certificate verify" /var/log/nginx/error.log[info] 604#604: *4 client SSL certificate verify error: (21:unable to verify the first certificate) while reading client request headers, client: 127.0.0.1, server: localhost ...[info] 604#604: *6 client SSL certificate verify error: (20:unable to get local issuer certificate) while reading client request headers, client: 127.0.0.1, server: localhost ...The numbers are OpenSSL error codes. Module 6 has a table of the common ones.
Go deeper
Section titled “Go deeper”- nginx
ngx_http_ssl_module— everyssl_directive used above. - RFC 8446, section 4.3.2 — the TLS 1.3 CertificateRequest message.
Check yourself
Tap a card to flip it. Nothing is scored or saved.
Progress is saved in this browser only.