Forwarding Client Certificates with NGINX Ingress
If you are building an application service, there are several ways to authenticate an incoming request from another application. Using API keys is one way. Another is to have the application make the request (which we’ll refer to in the rest of this guide as the client) and send a certificate to authenticate itself. While we might commonly associate the TLS protocol with certificates being sent by the server-side of the request and authenticating them, such as when we browse to a
https:// website in our browser, TLS also supports clients sending certificates 1.
What advantage do client certificates offer compared to API keys? As Cloudflare2 puts it,
In this post, we’ll look at how to configure NGINX Ingress to forward or pass-through client certificates to your application service without NGINX Ingress performing client certificate validation of its own. This is useful if you already have your client certificate validation logic in your application, and you’d like to deploy that application on a Kubernetes cluster using NGINX Ingress.
Place your certificate authority (CA) certificate (if you have just one) or concatenate the CA certificates (if you have multiple) into a file named
# if single CA certificate cat certificate.crt > ca.crt # if multiple CA certificates cat certificate1.crt certificate2.crt > ca.crt
Create a secret containing the CA certificate(s). Take note that the file in the secret containing the CA certificate(s) must be named
ca.crt. On the other hand, you may name the secret however you wish.
kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
For the rest of the guide, we’ll assume this secret is named
ca-secretin the namespace
Add the following annotations on your NGINX Ingress resource:
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: # Specify the secret containing CA certificates in the form <namespace>/<secret name> nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret" # Specify that certificates are to be passed on nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true" # Do not fail request if no or an otherwise invalid certificate is provided nginx.ingress.kubernetes.io/auth-tls-verify-client: "optional" name: my-ingress namespace: default
With this configuration, if the client does not send certificates in their request, NGINX Ingress still allows the request to your application. Whereas with the following configuration, the client must send certificates in their requests to your application. When the client does not send certificates in their requests, NGINX Ingress responds with a 400 Bad Request error.
apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: annotations: # Specify the secret containing CA certificates in the form <namespace>/<secret name> nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret" # Specify that certificates are to be passed on nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true" name: my-ingress namespace: default
By default, NGINX Ingress places the URL-encoded PEM client certificate in the
ssl-client-cert header, for example
This corresponds to the NGINX variable
For other values to
auth-tls-verify-client, as well as additional verification configurations such as validation depth, refer to the NGINX Ingress documentation on client certificate authentication.