In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Kong Logo
header icon

Upstream TLS

Kong Enterprise only: This plugin is only available with a Kong Enterprise subscription. Please inquire about Kong Enterprise by contacting us, or start a free trial today.

Enable TLS on upstream traffic by providing Kong with a list of trusted certificates.

This plugin is deprecated in Kong Enterprise version 1.3, and removed in version 1.5.


Starting with Kong 1.3.0.0:

To configure Upstream TLS, use the NGINX directives proxy_ssl_trusted_certificate, proxy_ssl_verify, and proxy_ssl_verify_depth instead of the Upstream TLS plugin. Instructions on how to inject NGINX directives to Kong can be found here. This plugin is only functional for Kong Enterprise versions 0.35 and 0.36.

Configuration Reference

You can configure this plugin using the Kong Admin API or through declarative configuration, which involves directly editing the Kong configuration file.

Enabling the plugin globally

A plugin which is not associated to any Service, Route, or Consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Kong Admin API
Kubernetes
Declarative (YAML)

For example, configure this plugin globally with:

$ curl -X POST http://<admin-hostname>:8001/plugins/ \
    --data "name=upstream-tls"  \
    --data "config.trusted_certificates="

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-upstream-tls>
  labels:
    global: \"true\"
config: 
  trusted_certificates: 
plugin: upstream-tls

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: upstream-tls
  config: 
    trusted_certificates:

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form ParameterDescription
nameThe name of the plugin to use, in this case upstream-tls.
enabled

default value: true		Whether this plugin will be applied.
config.verify_mode
optional

default value:

none

Sets the certification verification mode flags. peer enables client peer validation. none disables client peer validation.
config.verify_depth
optional

default value:

4

Set the maximum validation chain depth
config.trusted_certificates
required

PEM-encoded public certificate authorities of the upstream

In Enterprise versions 0.35 and 0.36, Upstream TLS can be added on top of an existing Service by executing the following request on your Kong server:

$ curl -X POST http://kong:8001/services/1e6507e9-5c72-4dc2-9a3a-5131c4c5bea6/plugins \
    --form "name=upstream-tls" \
    --form "config.verify_mode=peer" \
    --form "config.trusted_certificates=@path_to_cert.pem" \
    --form "config.verify_depth=2"

service: the id or name of the Service that this plugin configuration will target.

It can also be applied globally (for every Route, Service, or API) using the http://kong:8001/plugins/ endpoint.

Known Issues

PATCH requests to the trust_certificates configuration will not take affect until Kong is reloaded. This can be accomplished with the kong reload command.