How to configure a Kong service to perform upstream MTLS

How can Kong services be configured to negotiate MTLS with an upstream?

MTLS with an upstream service requires several components:

• The ability to provide a client certificate with the proxied request.
• The ability to verify the upstream’s presented server certificate.

1. Set up the client certificate (service level).

   a) Install the client certificate into Kong Manager’s Certificates section or via the Admin API. See the Certificate API documentation.

   Example:

   curl -X POST \
     http://localhost:8001/certificates \
     -H 'Content-Type: multipart/form-data' \
     -F cert=@./client-cert.pem \
     -F key=@./client-cert.key \
     -H "kong-admin-token:admin"

   Copied!

   If installing the certificate via CLI / Admin API, a successful response will include a certificate object id. Kong Manager will also show this ID and allow it to be retrieved.

   b) Use the certificate ID obtained in step 1, and enter it into the config.client_certificate field in the service. See the Service API documentation.

   Whenever a request is proxied to that service, the certificate associated with that id will be used as a client certificate.

   Further reading: Why do I have to add the private key with my client certificate?

2. Set up the CA certificate (service level).

   a) Install the CA certificate as in the previous step 1a, except use the CA Certificates API this time.

   Example:

   curl -X POST \
     http://localhost:8001/ca_certificates \
     -H 'Content-Type: multipart/form-data' \
     -F cert=@./ca-cert.pem \
     -H "kong-admin-token:admin"

   Copied!

   Note: You only need to add the certificate(s) for CA Certs. Private keys are not required / accepted.

   b) As with step 1b, use the CA certificate object id and enter it into the config.ca_certificates field in the service.

   When Kong does TLS negotiation with the upstream service, the CA Cert associated with that id will be used to verify the upstream server cert.

3. Set up the client certificate (global).

   Nginx can use 2 directives to set a global client certificate which will attach to all services.

   KONG_CLIENT_SSL_CERT and KONG_CLIENT_SSL_CERT_KEY can be used to indicate the path of the certificate and key that will be used with client certificate negotiation.

4. Set up the CA certificate (global).

   Nginx can use a directive to set a CA cert to verify all upstream server certificates without needing to modify all service configs.

   KONG_NGINX_PROXY_PROXY_SSL_TRUSTED_CERTIFICATE contains the path to a PEM file that can hold multiple CA Root certificates for verifying ALL upstream server certificates.

Further reading: Defining SSL certs and where to use them