--- title: "How to Configure Mutual TLS (mTLS) with Nginx on Ubuntu" description: "Create a private CA with OpenSSL, issue server and client certificates, and require client certificates in Nginx on Ubuntu 24.04 to protect an internal API." category: "Proxy and Load Balancing" language: en source: https://cubepath.com/docs/proxy-and-load-balancing/mtls-mutual-tls-configuration updated: 2026-09-25 --- # How to Configure Mutual TLS (mTLS) with Nginx on Ubuntu With regular HTTPS only the server proves its identity. Mutual TLS (mTLS) adds the other direction: the client must also present a certificate signed by a CA the server trusts, or the TLS handshake is rejected before any request reaches your application. This makes mTLS a good fit for service-to-service APIs, admin endpoints and IoT devices. In this tutorial you will create a small private CA with OpenSSL, issue a server and a client certificate, configure Nginx on Ubuntu 24.04 to require client certificates, and handle revocation and renewal. ## Prerequisites To follow this tutorial you need: - A server running Ubuntu 24.04 LTS, for example a CubePath VPS, with Nginx installed (`sudo apt install nginx`). - A non-root user with `sudo` privileges. - A hostname for the protected service. This guide uses `api.your_domain`. It does not need a public DNS record for the local tests. - OpenSSL, which is preinstalled on Ubuntu 24.04 (version 3.0). ## Step 1 - Creating a private certificate authority The CA signs every certificate in this setup, and whoever holds its private key can issue certificates that your server will accept. Create it in a private working directory, and in production keep the CA key on a separate, well protected machine rather than on the web server. ```bash mkdir -p ~/mtls && cd ~/mtls chmod 700 ~/mtls ``` Generate a 4096-bit RSA key for the CA, protected by a passphrase. You will be asked for it every time you sign a certificate: ```bash openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -aes256 -out ca.key ``` Create the self-signed CA certificate, valid for 10 years: ```bash openssl req -x509 -new -key ca.key -sha256 -days 3650 -subj "/CN=Example Internal CA" -out ca.crt ``` Confirm that it is marked as a CA: ```bash openssl x509 -in ca.crt -noout -subject -ext basicConstraints ``` ```output subject=CN = Example Internal CA X509v3 Basic Constraints: critical CA:TRUE ``` ## Step 2 - Issuing the server certificate The server certificate proves the identity of `api.your_domain` to clients. Modern clients check the Subject Alternative Name (SAN), not the Common Name, so the SAN is required. Create an ECDSA key and a certificate signing request (CSR): ```bash openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out server.key openssl req -new -key server.key -subj "/CN=api.your_domain" -out server.csr ``` Create an extensions file that restricts the certificate to server authentication: ```bash nano server.ext ``` ```ini basicConstraints = CA:FALSE keyUsage = critical, digitalSignature extendedKeyUsage = serverAuth subjectAltName = DNS:api.your_domain ``` Sign the CSR with the CA: ```bash openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 397 -sha256 -extfile server.ext -out server.crt ``` Verify the certificate against the CA: ```bash openssl verify -CAfile ca.crt server.crt ``` ```output server.crt: OK ``` > Tip: If the service is also public, you can use a Let's Encrypt certificate as the server certificate and keep the private CA only for client certificates. Clients then do not need your CA to trust the server. ## Step 3 - Issuing a client certificate Each client (a service, a device or a person) gets its own key and certificate, so you can identify and revoke clients individually. Name the certificate after the client, here `billing-service`: ```bash openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out billing-service.key openssl req -new -key billing-service.key -subj "/CN=billing-service" -out billing-service.csr ``` Create the extensions file for client authentication: ```bash nano client.ext ``` ```ini basicConstraints = CA:FALSE keyUsage = critical, digitalSignature extendedKeyUsage = clientAuth ``` Sign it: ```bash openssl x509 -req -in billing-service.csr -CA ca.crt -CAkey ca.key -CAserial ca.srl -days 365 -sha256 -extfile client.ext -out billing-service.crt ``` Check the result and note the serial number, which you will need for revocation: ```bash openssl x509 -in billing-service.crt -noout -subject -serial -enddate ``` ```output subject=CN = billing-service serial=5C1A9E3F0B7D4A21C6E08F13A9B2D7640E1F3A58 notAfter=Sep 25 10:40:12 2027 GMT ``` Deliver `billing-service.crt` and `billing-service.key` to the client over a secure channel, together with `ca.crt` so it can verify the server. Never send the CA key. ## Step 4 - Installing the certificates on the server Copy the server certificate, its key and the CA certificate to a directory that only root can read: ```bash sudo install -d -m 0750 /etc/nginx/mtls sudo install -m 0644 ca.crt server.crt /etc/nginx/mtls/ sudo install -m 0600 server.key /etc/nginx/mtls/ ``` The CA private key (`ca.key`) stays in `~/mtls` or, better, on another machine. ## Step 5 - Requiring client certificates in Nginx Create a site for the API: ```bash sudo nano /etc/nginx/sites-available/api.conf ``` ```nginx server { listen 443 ssl; listen [::]:443 ssl; server_name api.your_domain; ssl_certificate /etc/nginx/mtls/server.crt; ssl_certificate_key /etc/nginx/mtls/server.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_client_certificate /etc/nginx/mtls/ca.crt; ssl_verify_client on; ssl_verify_depth 2; location / { default_type text/plain; return 200 "Hello $ssl_client_s_dn\n"; } } ``` - `ssl_client_certificate` is the CA that client certificates must be signed by. - `ssl_verify_client on` rejects any request without a valid client certificate. Use `optional` if some locations must stay open, and check `$ssl_client_verify` in the protected ones. - `ssl_verify_depth 2` allows a client certificate signed directly by the root CA or by one intermediate. - `$ssl_client_s_dn` contains the client certificate subject. The `return` line is only for testing. Enable the site and reload Nginx: ```bash sudo ln -s /etc/nginx/sites-available/api.conf /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx ``` If UFW is active, allow HTTPS: ```bash sudo ufw allow 443/tcp ``` ## Step 6 - Testing the mTLS connection Run the tests from `~/mtls`. The `--resolve` option sends `api.your_domain` to the local server without needing DNS. Request the API with the client certificate: ```bash curl --cacert ca.crt --cert billing-service.crt --key billing-service.key --resolve api.your_domain:443:127.0.0.1 https://api.your_domain/ ``` ```output Hello CN=billing-service ``` Now try without a client certificate: ```bash curl --cacert ca.crt --resolve api.your_domain:443:127.0.0.1 https://api.your_domain/ ``` ```output 400 No required SSL certificate was sent ... ``` A certificate signed by a different CA is also rejected, with `400 The SSL certificate error`. The failure reason is recorded in `/var/log/nginx/error.log`. ## Step 7 - Passing the client identity to the application In a real setup Nginx proxies to an application, which usually wants to know which client is calling. Replace the test `location` with a proxy that forwards the verified identity in headers: ```nginx location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Client-Verify $ssl_client_verify; proxy_set_header X-Client-DN $ssl_client_s_dn; proxy_set_header X-Client-Serial $ssl_client_serial; } ``` The application can then authorize each client by its DN, for example allowing `CN=billing-service` to call `/invoices` but not `/admin`. Make sure the application port is only reachable from Nginx, otherwise a client could send these headers directly. Test and reload after the change: ```bash sudo nginx -t && sudo systemctl reload nginx ``` ## Step 8 - Revoking a client certificate If a client key leaks or a service is decommissioned, its certificate must stop working before it expires. For a small number of clients, the simplest approach is a denylist of serial numbers using Nginx's `map`. Add the map at the top of `/etc/nginx/sites-available/api.conf`, outside the `server` block: ```nginx map $ssl_client_serial $client_revoked { default 0; 5C1A9E3F0B7D4A21C6E08F13A9B2D7640E1F3A58 1; } ``` Use the serial from Step 3 without the `serial=` prefix. Inside the `server` block, reject revoked clients: ```nginx if ($client_revoked) { return 403; } ``` Reload Nginx and repeat the first test from Step 6. It now returns `403 Forbidden`. When you manage many clients, run a proper CA with `openssl ca` (or a tool such as step-ca) that tracks issued certificates and publishes a Certificate Revocation List, and point Nginx at it with the `ssl_crl` directive. Remember that Nginx only reads the CRL on reload, and rejects every client certificate once the CRL has expired. ## Step 9 - Renewing certificates Client certificates in this guide are valid for one year and the server certificate for 397 days. Check the expiry date of a certificate on the server with: ```bash sudo openssl x509 -in /etc/nginx/mtls/server.crt -noout -enddate ``` To renew a client certificate, sign a new CSR (you can reuse the key or create a new one) as in Step 3 and deploy it to the client before the old one expires. Both certificates are valid at the same time, so there is no downtime. Short lifetimes (weeks instead of years) with automated renewal limit the damage of a stolen key. To replace the CA itself, create the new CA, then put both CA certificates in `ssl_client_certificate` during the transition: ```bash cat ca.crt new-ca.crt | sudo tee /etc/nginx/mtls/ca-bundle.crt > /dev/null ``` Point `ssl_client_certificate` to `ca-bundle.crt`, reload, reissue all client certificates from the new CA, and finally remove the old CA from the bundle. ## HAProxy equivalent If HAProxy terminates TLS instead of Nginx, the same policy goes on the `bind` line. HAProxy expects the certificate and key in one PEM file: ```bash sudo install -d -m 0750 /etc/haproxy/mtls cat server.crt server.key | sudo tee /etc/haproxy/mtls/server.pem > /dev/null sudo chmod 600 /etc/haproxy/mtls/server.pem sudo install -m 0644 ca.crt /etc/haproxy/mtls/ ``` ```haproxy frontend api_in bind :443 ssl crt /etc/haproxy/mtls/server.pem ca-file /etc/haproxy/mtls/ca.crt verify required http-request set-header X-Client-DN %{+Q}[ssl_c_s_dn] default_backend api_back backend api_back server app1 127.0.0.1:8080 check ``` `verify required` rejects the handshake when the client has no valid certificate, and `crl-file` on the same `bind` line loads a CRL. ## Troubleshooting - **`400 No required SSL certificate was sent`**: the client did not present a certificate. Check the certificate and key paths in the client, and make sure no other proxy terminates TLS between the client and Nginx. - **`400 The SSL certificate error`**: the client certificate was not signed by the CA in `ssl_client_certificate`, has expired, lacks the `clientAuth` extended key usage (check with `openssl x509 -in client.crt -noout -ext extendedKeyUsage`), or the chain is deeper than `ssl_verify_depth`. The exact reason is in `/var/log/nginx/error.log`. - **curl: `SSL certificate problem: unable to get local issuer certificate`**: the client does not trust the server certificate. Pass the CA with `--cacert ca.crt`. - **curl: `no alternative certificate subject name matches`**: the hostname in the URL is not in the server certificate's SAN. Reissue the server certificate with the correct `subjectAltName`. ## Conclusion You built a private CA, issued server and client certificates, and configured Nginx so that only clients with a certificate from your CA can reach the API. You also passed the client identity to the application, revoked a certificate and planned renewals. As next steps, automate certificate issuance and renewal with a dedicated CA such as step-ca, move the CA key off the server, and combine mTLS with authorization in your application based on the client certificate's subject.