Home / Kong Gateway
Edit
Report

Using SSL certificates in Kong Gateway

Uses: Kong Gateway
Related Documentation
All Gateway Documentation
Plugins
Mutual TLS Authentication Header Cert Authentication
Tags
#certificates #ssl
Related Resources
Certificate entity
CA Certificate entity
SNI entity
Gateway Service entity
Configuration reference

Kong Gateway uses three types of certificates:

  • Client certificates: Used to verify a client as a Consumer of a Service
  • Server certificates: Used to verify that a server is the hostname it claims to be
  • CA Root certificates: Used to verify that client and server certificates are authentic

Client certificates

The following table shows how to configure client certificates in Kong Gateway:

Use Case

Description

Method
Global client certificate Send a single cert globally with all upstream proxy requests. Set client_ssl_cert and client_ssl_cert_key in kong.conf or as environment variables.
Service-level client certificate Configure Gateway Services to send individual client certificates to their upstream applications. Upload the certificate and private key to a Certificate entity, then pass the entity’s ID to a Gateway Service.

CA certificates

The following table shows how to configure CA certificates in Kong Gateway:

Use Case

Description

Method
Global CA certificate Import a CA root certificate to cover verification of all upstream server certificates. Set the nginx_proxy_proxy_ssl_trusted_certificate parameter in kong.conf, or as an environment variable.

If you want to disable or enable verification of upstream server certificates globally, you can also set the nginx_proxy_proxy_tls_verify option.
Service-level CA certificate Define individual CA root certificates for each Gateway Service. Upload the certificate and private key to a CA Certificate entity, then pass the entity’s ID to a Gateway Service.
Verify client certificates Verify client certificates by passing CA certificates to the mTLS Auth plugin. Upload the certificate and private key to a CA Certificate entity, then pass the entity’s ID to the plugin via its ca_certificates parameter.
Verify client certificates sent in headers Verify client certificates sent in headers by passing CA certificates to the Header Cert Auth plugin. Upload the certificate and private key to a CA Certificate entity, then pass the entity’s ID to the plugin via its ca_certificates parameter.

Server certificates

The following table shows how to configure server certificates in Kong Gateway:

Use Case

Description

Method
Server certificates for SNIs Standard certificates that Kong Gateway presents if a specific domain is requested when a TLS handshake is attempted at the proxy. Upload certificates for SNIs using the Certificates entity, then create an SNI using the ID of the Certificate.

Configuring SSL connections through kong.conf

You can directly upload certificates and keys to Kong Gateway through configuration in kong.conf.

All of the following parameters can also be set via environment variables.

Parameter Description
admin_gui_ssl_cert

The SSL certificate for admin_gui_listen values with SSL enabled.

values:

  • absolute path to the certificate
  • certificate content
  • base64 encoded certificate content
admin_gui_ssl_cert_key

The SSL key for admin_gui_listen values with SSL enabled.

values:

  • absolute path to the certificate key
  • certificate key content
  • base64 encoded certificate key content
admin_ssl_cert

Comma-separated list of certificates for admin_listen values with TLS enabled.

See docs for ssl_cert for detailed usage.
admin_ssl_cert_key

Comma-separated list of keys for admin_listen values with TLS enabled.

See docs for ssl_cert_key for detailed usage.
client_ssl_cert

If client_ssl is enabled, the client certificate for the proxy_ssl_certificate directive.

This value can be overwritten dynamically with the client_certificate attribute of the Service object.

The certificate can be configured on this property with any of the following values:

  • absolute path to the certificate
  • certificate content
  • base64 encoded certificate content
client_ssl_cert_key

If client_ssl is enabled, the client TLS key for the proxy_ssl_certificate_key directive.

This value can be overwritten dynamically with the client_certificate attribute of the Service object.

The certificate key can be configured on this property with any of the following values:

  • absolute path to the certificate key
  • certificate key content
  • base64 encoded certificate key content
lua_ssl_trusted_certificate Default: system

Comma-separated list of certificate authorities for Lua cosockets in PEM format.

The special value system attempts to search for the “usual default” provided by each distro, according to an arbitrary heuristic. In the current implementation, the following pathnames will be tested in order, and the first one found will be used:

  • /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo)
  • /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)
  • /etc/ssl/ca-bundle.pem (OpenSUSE)
  • /etc/pki/tls/cacert.pem (OpenELEC)
  • /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7)
  • /etc/ssl/cert.pem (OpenBSD, Alpine)

system can be used by itself or in conjunction with other CA file paths.

When pg_ssl_verify is enabled, these certificate authority files will be used for verifying Kong’s database connections.

Certificates can be configured on this property with any of the following values:

  • system
  • absolute path to the certificate
  • certificate content
  • base64 encoded certificate content

See https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate
nginx_proxy_proxy_ssl_trusted_certificate

Path to a PEM file that can hold multiple CA Root certificates for verifying all upstream server certificates.
ssl_cert

Comma-separated list of certificates for proxy_listen values with TLS enabled.

If more than one certificate is specified, it can be used to provide alternate types of certificates (for example, ECC certificates) that will be served to clients that support them. Note that to properly serve using ECC certificates, it is recommended to also set ssl_cipher_suite to modern or intermediate.

Unless this option is explicitly set, Kong will auto-generate a pair of default certificates (RSA + ECC) the first time it starts up and use them for serving TLS requests.

Certificates can be configured on this property with any of the following values:

  • absolute path to the certificate
  • certificate content
  • base64 encoded certificate content
ssl_cert_key

Comma-separated list of keys for proxy_listen values with TLS enabled.

If more than one certificate was specified for ssl_cert, then this option should contain the corresponding key for all certificates provided in the same order.

Unless this option is explicitly set, Kong will auto-generate a pair of default private keys (RSA + ECC) the first time it starts up and use them for serving TLS requests.

Keys can be configured on this property with any of the following values:

  • absolute path to the certificate key
  • certificate key content
  • base64 encoded certificate key content
status_ssl_cert

Comma-separated list of certificates for status_listen values with TLS enabled.

See docs for ssl_cert for detailed usage.
status_ssl_cert_key

Comma-separated list of keys for status_listen values with TLS enabled.

See docs for ssl_cert_key for detailed usage.

Kong Gateway also provides many customization settings for SSL connections. See the Kong Configuration Reference for all available options.

Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support