Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Ingress Controller
2.2.x
  • Home icon
  • Kong Ingress Controller
  • Guides
  • Using mTLS with Kong
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.11.x (latest)
  • 2.10.x
  • 2.9.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • What is mTLS?
  • mTLS with Kong
  • Configure Kong to verify upstream server certificate
  • Configure Kong to present its certificate to the upstream server
    • Global Nginx directive
    • Per service annotation
You are browsing documentation for an outdated version. See the latest documentation here.

Using mTLS with Kong

This guide walks through on how to setup Kong to perform mutual-TLS authentication with an upstream service.

Please note that this guide walks through mTLS configuration between Kong and a Service and not Kong and a client or consumer.

What is mTLS?

Mutual authentication refers to two-way authencation, where the client and server, both can authenticate themselves to the other party.

With mutual TLS authentication, client and server both present TLS certificates to the other party (and can prove their identity using their private key) during the TLS handshake. They can verify the other’s certificate using the their trusted CAs.

mTLS with Kong

Kong 1.3 and above support mutual TLS authentication between Kong and the upstream service.

Let’s take a look at how one can configure it.

Configure Kong to verify upstream server certificate

Kong, by default, does not verify the certificate presented by the upstream service.

To enforce certificate verification, you need to configure the following environment variables on Kong’s container in your deployment:

KONG_NGINX_PROXY_PROXY_SSL_VERIFY="on"
KONG_NGINX_PROXY_PROXY_SSL_VERIFY_DEPTH="3"
KONG_NGINX_PROXY_PROXY_SSL_TRUSTED_CERTIFICATE="/path/to/ca_certs.pem"

These basically translate to NGINX directives to configure NGINX to verify certificates.

Please make sure that the trusted certificates are correctly mounted into Kong’s container and the path to certificate is correctly reflected in the above environment variable.

Configure Kong to present its certificate to the upstream server

In the above section, we achieved one side of mutual authentication, where Kong has been configured to verify the identity of the upstream server.

In this section, we will configure Kong to present its identity to the upstream server.

To configure this, you have two options, depending on your use-case. If you would like Kong to present its client certificate to each and every service that it talks to, you can configure the client certificate at the global level using Nginx directives. If you would like to configure a different certificate for each service that Kong talks to or want to configure Kong to present a client certificate only to a subset of all services that it is configured to communicate with, then you can configure that using an annotation on the Kubernetes Service resource.

Global Nginx directive

You need to configure two Nginx directives for this purpose:

  • proxy_ssl_certificate
  • proxy_ssl_certificate_key

You can mount the certificate and key pair using secrets into the Kong pod and then set the following two environment variables to set the above two directives:

KONG_NGINX_PROXY_PROXY_SSL_CERTIFICATE="/path/to/client_cert.pem"
KONG_NGINX_PROXY_PROXY_SSL_CERTIFICATE_KEY="/path/to/key.pem"

Once configured, Kong will present its client certificate to every upstream server that it talks to.

Per service annotation

To configure a different client certificate for each service or only for a subset of services, you can do so using the konghq.com/client-cert annotation.

To use the annotation, you first need to create a TLS secret with the client certificate and key in Kubernetes. The secret should be created in the same namespace as your Kubernetes Service to which Kong should authenticate itself.

Once the secret is in place, add the follow annotation on the service:

konghq.com/client-cert: <name-of-secret>

Kong will then use the TLS key-pair to authenticate itself against that service.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023