Using SSL certificates in Kong Gateway

Uses: Kong Gateway

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.
`tls_certificate_verify` Default: `off`	Toggles enforcement of TLS server certificate verification. When enabled, plugins and service entities cannot override or disable certificate verification for upstream connections.

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

Enforcing TLS verification globally v3.13+

You can set tls_certificate_verify to true to enforce global certificate verification when connecting to secure endpoints. When this setting is enabled, configurations containing Services or plugins where tls_verify is set to off will fail to be inserted or updated. You will need to manually update each Service or plugin instance to resolve this error.

When certificate verification is enforced:

Traditional deployments will fail to start if Kong Gateway detects insecure configurations. This happens when an upstream is configured to use a secure protocol (such as HTTPS) but certificate verification is disabled.
Hybrid deployments will fail to push such insecure configurations to Data Planes that start with this option enabled.

This feature is designed primarily for highly federated environments, where platform operators need to guarantee that all teams and users deploying configuration through Kong Gateway adhere to certificate-verification requirements.

Keep in mind that enabling certificate verification does not change how Kong Gateway validates certificates themselves. If you configure Services or system components (such as Postgres or Redis) with certificates that are invalid or self-signed without an appropriate trusted CA, Kong Gateway will be unable to establish those connections. This behavior is not new. However, enabling global enforcement may surface misconfigurations that were previously unnoticed.