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

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.

Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.

Configuration

Global plugins

  • Using a database, all plugins can be configured using the http://kong:8001/plugins/ endpoint.
  • Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

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

PEM-encoded public certificate authorities of the upstream

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

Only one root CA cert can be used to verify against the upstream. If you upload a pem file with multiple certs it must be the first certificate in your uploaded pem file.