Skip to content
Module 04

mTLS: secure a service with nginx

Make both sides prove who they are. Configure nginx to require client certificates and test with curl.

mTLSIntermediate 35 min

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.

Clientclient.crtServerserver.crt1. ClientHello2. Server certificate + CertificateRequest3. Client certificate + proof of key4. Both verified against the CAEncrypted, mutually authenticated

You need the CA from module 2 running before you start. Work in a new folder:

terminal
mkdir -p ~/pki-lab/mtls && cd ~/pki-lab/mtls

Request a certificate for localhost. Enter the provisioner password when asked.

terminal
step ca certificate localhost server.crt server.key
Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Certificate: server.crt
✔ Private Key: server.key
terminal
step ca certificate alice client.crt client.key
Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Certificate: client.crt
✔ Private Key: client.key

The 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.

Copy the root certificate into your working folder:

terminal
cp $(step path)/certs/root_ca.crt .

Create a folder for nginx to read from:

terminal
sudo mkdir -p /etc/pki-lab

Copy the server certificate, server key and root into it:

terminal
sudo cp server.crt server.key root_ca.crt /etc/pki-lab/
/etc/nginx/conf.d/mtls.conf
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:

terminal
sudo nginx -t
Expected output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the config:

terminal
sudo nginx -s reload

On macOS with Homebrew, the config folder is $(brew --prefix)/etc/nginx/servers/ and you don’t need sudo.

Without a client certificate, nginx rejects you:

terminal
curl --cacert root_ca.crt https://localhost:8443
Expected output (excerpt)
<html>
<head><title>400 No required SSL certificate was sent</title></head>

With one, you’re in:

terminal
curl --cacert root_ca.crt \
--cert client.crt --key client.key \
https://localhost:8443
Expected output
Hello, 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.

Make a copy of the client certificate with only the leaf:

terminal
awk '/BEGIN/{n++} n==1' client.crt > client-leaf.crt
terminal
curl --cacert root_ca.crt \
--cert client-leaf.crt --key client.key \
https://localhost:8443
Expected output (excerpt)
<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.

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:

terminal
curl --cacert root_ca.crt \
--cert other.crt --key other.key \
https://localhost:8443
Expected output (excerpt)
<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:

terminal
sudo grep "client SSL certificate verify" /var/log/nginx/error.log
Expected output (excerpt)
[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.

Check yourself

Tap a card to flip it. Nothing is scored or saved.

Progress is saved in this browser only.