Nginx TLS — Practical Zero Trust

How to get and renew Nginx TLS certificates

Written September 15, 2021

Zero Trust or BeyondProd approaches require authenticated and encrypted communications everywhere. TLS is the cryptographic protocol that powers encryption for all your technologies. For TLS, you need certificates. This practitioner's tutorial provides instructions for automating Nginx TLS certificate renewal and enabling server-side encryption.

Try it

Create a private key and request a certificate

Before you can configure Nginx TLS, you will need a certificate issued by a trusted certificate authority (CA). If you already have a certificate, private key, and CA root certificate from your organization's existing CA, you can skip to the Nginx TLS configuration section below. If you need to generate a certificate, you can:

Use a free hosted Smallstep Certificate Manager authority

Roll your own with open source step-ca

This tutorial is designed for private networks, not publicly trusted websites or endpoints. If you are looking to automate certificates for public websites, servers, or endpoints, we recommend using Let's Encrypt and the ACME instructions below.

To request a certificate from your CA using the step CLI, bootstrap your CA with step ca bootstrap and run the following command (sub the server name for the actual name / DNS name of your Nginx server).

step ca certificate "myserver.example.net" server.crt server.key

Your certificate and private key will be saved in server.crt and server.key respectively.

Request a copy of your CA root certificate, which will be used to make sure each application can trust certificates presented by other applications.

step ca root ca.crt

Your certificate will be saved in ca.crt.

Configure Nginx to use the certificate

In your Nginx configuration's server block, enable ssl for the listening socket and specify the locations of the server's certificate and private key. We'll also tell Nginx to use TLS protocols and our preferred ciphers:

server {
    listen              443 ssl;
    server_name         myserver.example.net;
    ssl_certificate     /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    # ...
}

Send a reload signal to Nginx to apply your new configuration:

nginx -s reload

Test Nginx TLS configuration

To make sure Nginx is presenting a valid certificate, you can use the curl command, passing it your root certificate for use in verifying the server.

$ curl --cacert ca.crt https://myserver.example.net
HTTP/2 200
...

Operationalize It

Select a provisioner

Smallstep CAs use provisioners to authenticate certificate requests using passwords, one-time tokens, single sign-on, and a variety of other mechanisms.

ACME (RFC8555) is an open standard, used by Let's Encrypt, for authenticating certificate requests. To use ACME on a private network you need to run an ACME server. ACME is harder to setup, but has a large client ecosystem (some software even has built-in support).

Other provisioners use the open source step CLI and do not require a local network agent. The instructions below focus on the JWK provisioner, but can be repurposed with small tweaks to operationalize all non-ACME provisioners.

To learn more, see Configuring step-ca Provisioners.

Show me instructions for...

ACME

Other provisioners

The right provisioner depends on your operational environment.

The JWK provisioner is the most general-purpose provisioner. It supports password and one-time token-based authentication. To add a JWK provisioner called nginx to a hosted Certificate Manager authority (if you haven't already), run:

step ca provisioner add nginx --type JWK --create --x509-default-dur 720h

For instructions on adding provisioners to open source step-ca, or to learn more about other provisioner types, see Configuring step-ca Provisioners.

Configure Nginx TLS Certificate Automation

We've created a systemd-based certificate renewal timer that works with step. Check out our documentation on Renewal using systemd timers for background on how these timers work.

To install the certificate renewal unit files, run:

cd /etc/systemd/system
sudo curl -sL https://files.smallstep.com/cert-renewer@.service \
     -o cert-renewer@.service
sudo curl -sL https://files.smallstep.com/cert-renewer@.timer \
     -o cert-renewer@.timer

The renewal timer will check your certificate files every five minutes and renew them after two-thirds of their lifetime has elapsed.

The cert-renewer@.service and cert-renewer@.timer files define a service unit template. Templates are never run directly, but we will run an instance of them for Nginx certificate renewals. That service will be called cert-renewer@nginx.service, which parallels the nginx.service unit name used by Nginx on systemd-based Linux distributions. Because the two units share this value in their name, the cert-renewer@nginx.service renewer will attempt to reload or restart nginx.service after it renews the certificate.

To start the renewal timer, run:

sudo systemctl daemon-reload
sudo systemctl enable --now cert-renewer@nginx.timer

You'll see that the timer is active, by checking the output of systemctl list-timers.

There are various approaches for configuring TLS certificate renewal in Kubernetes. For this tutorial, we will assume you are using Helm and will manage certificate renewal using the open source cert-manager project. You may repurpose various pieces for your own configuration by following the cert-manager or Nginx documentation.

First, install cert-manager in your cluster with Helm:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true

In cert-manager, a custom resource type Certificate represents each TLS certififcate and specifies how to store it.

Create a new Certificate resource myserver-certificate.yaml for your Nginx server. Make sure you specify the same DNS name configured above, and keep track of the Kubernetes secret name where cert-manager will store your certificate and private key.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: myserver
spec:
  secretName: myserver-tls
  duration: 720h
  dnsNames:
    - myserver.example.net
  issuerRef:
    name: my-ca
    kind: StepIssuer
    group: certmanager.step.sm

Customize the Certificate name, secretName, and issuer name to suit your own naming style in your Kubernetes cluster, then apply it with kubectl.

kubectl apply -f myserver-certificate.yaml

This configuration specifies that cert-manager should issue and renew a TLS certificate with the DNS name myserver.example.net and store the certificate and private key in a Kubernetes secret named myserver-tls. The certificate is valid for 720 hours, and cert-manager will automatically renew it before expiration and update the myserver-tls secret.

You'll also notice the above Certificate resource has an issuerRef specifying a cert-manager StepIssuer resource named my-ca. Before cert-manager knows how to use your CA to issue and renew your certificate, we'll need to create that StepIssuer resource and configure it to point to your private CA.

First, let's grab the name and key kid from the JWK provisioner we created earlier.

step ca provisioner list

Next, get a base64-encoded version of your CA root certificate:

step ca root -f >(step base64) 2> /dev/null

Create my-ca-issuer.yaml and fill in the CA URL and provisioner details with your own. caBundle refers to the base64-encoded version of your root certificate.

apiVersion: certmanager.step.sm/v1beta1
kind: StepIssuer
metadata:
  name: my-ca
  namespace: default
spec:
  url: https://my-ca-url.my-team.ca.smallstep.com
  caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJpekNDQVRHZ0F3SUJBZ0lRTytFQWg4eS8wVjlQMFhwSHJWajVOVEFLQmdncWhrak9QUVFEQWpBa01TSXcKSUFZRFZRUURFeGxUZEdWd0lFTmxjblJwWm1sallYUmxjeUJTYjI5MElFTkJNQjRYRFRFNU1EZ3hNekU1TVRVdwpNbG9YRFRJNU1EZ3hNREU1TVRVd01sb3dKREVpTUNBR0ExVUVBeE1aVTNSbGNDQkRaWEowYVdacFkyRjBaWE1nClVtOXZkQ0JEUVRCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFNVkw3VzBQbTNvSlVmSTR3WGQKa2xERW5uNVhTbWo4NlgwYW1DQTBnY08xdElUUG1DVzNCcGU0cE9vV1V2WlZlUWRvU2NxN3pua1V0Mi9HMnQxTgo3MWlqUlRCRE1BNEdBMVVkRHdFQi93UUVBd0lCQmpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvQWdFQk1CMEdBMVVkCkRnUVdCQlJ1Y1ByVm5QdlpOMHI0QVU5TGcyL2VCcng3a2pBS0JnZ3Foa2pPUFFRREFnTklBREJGQWlCUlJBdGsKNXpMY0doQ2FobVBuVzIwZExpdEMzRVdNaVE0bERwN2FFeitFUEFJaEFJOWZWczVxb0l0bVQ4anA2WktVNVEydQphRFBrOGsyQ25OMjdyRnNZV3VwTAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
  provisioner:
    name: nginx
    kid: N6I99Yuk7iGDMk_eW3QaN2admCsrC9UuDN27dlFXUOs
    passwordRef:
      name: my-ca-provisioner-password
      key: password

You'll notice the passwordRef configuration above, which declares a secret where step-issuer can expect to find your JWK provisioner password. You can name this whatever you'd like. Create the secret in your cluster, then apply your StepIssuer resource.

kubectl create secret generic my-ca-provisioner-password --from-literal=password=Y4nys7f11
kubectl apply -f my-ca-issuer.yaml

If all went as expected now that both your Certificate and your StepIssuer are configured, cert-manager should have reached out to your Smallstep CA, issued (or begun issuing) the certificate, and created the myserver-tls secret with your certificate and private key.

Now that your certificate is issued (and kept updated) in the myserver-tls secret, you'll need to configure Nginx to actually use that certificate.

In the "Try It" section above, we showed how to configure a standalone Nginx server to use a certificate and private key. However, in Kubernetes, it's much more common to have Nginx deployed as an ingress controller.

For this example, we will assume that you already have ingress-nginx deployed into your cluster. In that case, telling your ingress to make use of the certificate and private key in the myserver-tls secret is as easy as adding a tls block to your exsting Ingress resource.

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: myserver
  labels: ...
  annotations: ...
spec:
  rules:
    - host: myserver.example.net
      http:
        paths:
          - backend:
              serviceName: my-service
              servicePort: 5000
            path: /
  tls:
    - hosts:
        - myserver.company.net
      secretName: myserver-tls

Voila! ingress-nginx will pick up this tls configuration and automatically serve the renewed certificate each time the myserver-tls secret is updated.

As in the section above, you can test your configuration using curl and your CA root certificate.

Distribute your root certificate to end users and systems

Once Nginx TLS is configured, you'll need to make sure that clients know to trust certificates signed by your CA. For certificates signed by a public CA (like Let's Encrypt), most clients already include the CA root certificate in their trust stores for certificate verification. But, for a private CA, you will need to explicitly add your CA's root certificate to your clients' trust stores.

The step CLI includes a utility command for this purpose on many systems:

step certificate install ca.crt

Rather than manually running the above for each machine that needs to trust your CA, most teams will use some form of automation to distribute the root certificate. Depending on your needs and your IT or DevOps team's approach, this may be a configuration management tool (like Ansible or Puppet), a Mobile Device Management (MDM) solution, or something else. Some examples:

Use Ansible to add ca.crt directly to the ca-ceritficates bundle on linux VMs so running applications trust the API servers they call

Bake ca.crt directly into base Docker images for gRPC so gRPC clients can always reference the trusted CA

Store ca.crt in a Kubernetes Secret and inject it into an environment variable for access from application code

Use Jamf to install ca.crt in the trust stores of every employee Macbook so their web browsers trust internal websites

Use Puppet to run step certificate install ca.crt on target machines that want curl to implicity trust the CA

Store ca.crt in a Kubernetes ConfigMap and mount it to pods for reference on the filesystem

Alternatively, many clients support passing the CA root certificate as a flag or argument at runtime.

Nginx TLS — Practical Zero Trust

How to get and renew Nginx TLS certificates

Try it

Create a private key and request a certificate

Configure Nginx to use the certificate

Test Nginx TLS configuration

Operationalize It

Select a provisioner

Show me instructions for...

Configure Nginx TLS Certificate Automation

Distribute your root certificate to end users and systems

Further reading

Contribute to this document

Subscribe to updates

Learn

Products

Pricing

Documentation

Open Source

Company