Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      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
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • 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
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway 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 Gateway
3.3.x
  • Home icon
  • Kong Gateway
  • Production Deployment
  • Networking
  • Configuring PostgreSQL TLS
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.10.x (latest)
  • 3.9.x
  • 3.8.x
  • 3.7.x
  • 3.6.x
  • 3.5.x
  • 3.4.x (LTS)
  • 3.3.x
  • 2.8.x (LTS)
  • Archive (3.0.x and pre-2.8.x)
  • Introduction
    • Overview of Kong Gateway
    • Support
      • Version Support Policy
      • Third Party Dependencies
      • Browser Support
      • Software Bill of Materials
    • Stability
    • Release Notes
    • Breaking Changes
      • Kong Gateway 3.3.x
      • Kong Gateway 3.2.x
      • Kong Gateway 3.1.x
      • Kong Gateway 3.0.x
      • Kong Gateway 2.8.x or earlier
    • Key Concepts
      • Services
      • Routes
      • Consumers
      • Upstreams
      • Plugins
    • How Kong Works
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
  • Get Started with Kong
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
  • Kong in Production
    • Deployment Topologies
      • Overview
      • Kubernetes Topologies
      • Hybrid Mode
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
    • Installation Options
      • Overview
      • Kubernetes
        • Overview
        • Install Kong Gateway
        • Configure the Admin API
        • Install Kong Manager
        • Install Developer Portal
      • Docker
        • Using docker run
        • Build your own Docker images
      • Linux
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Post-installation
        • Set up a data store
        • Apply Enterprise license
        • Enable Kong Manager (Enterprise)
    • Running Kong
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
    • Access Control
      • Start Kong Gateway Securely
      • Programmatically Creating Admins
      • Enabling RBAC
    • Licenses
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
    • Networking
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
      • PostgreSQL TLS
        • Configure PostgreSQL TLS
        • Troubleshooting PostgreSQL TLS
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
    • Monitoring
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Health Check Probes
    • Tracing
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
    • Logging
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
    • Configure a gRPC service
    • Use the Expressions Router
    • Upgrade and Migration
      • Upgrading Kong Gateway 3.x.x
      • Backup and Restore
      • Upgrade Strategies
        • Dual-Cluster Upgrade
        • In-Place Upgrade
        • Blue-Green Upgrade
        • Rolling Upgrade
      • Upgrade from 2.8 LTS to 3.4 LTS
      • Migrate from OSS to Enterprise
      • Migration Guidelines Cassandra to PostgreSQL
      • Breaking Changes
  • Kong Gateway Enterprise
    • Overview
    • Kong Vitals
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
    • Secrets Management
      • Overview
      • Getting Started
      • Advanced Usage
      • Backends
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Cloud Secret Manager
        • HashiCorp Vault
      • How-To
        • Securing the Database with AWS Secrets Manager
      • Reference Format
    • Dynamic Plugin Ordering
      • Overview
      • Get Started with Dynamic Plugin Ordering
    • Dev Portal
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
      • Authentication and Authorization
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
      • Application Registration
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
        • Enable External Authentication
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
      • Customize Dev Portal
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • Configure Data Plane Resilience
    • About Control Plane Outage Management
    • FIPS 140-2
      • Overview
      • Install the FIPS Compliant Package
    • Authenticate your Kong Gateway Amazon RDS database with AWS IAM
  • Kong Manager
    • Overview
    • Enable Kong Manager
    • Get Started with Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
    • Authentication and Authorization
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
      • LDAP
        • Configure LDAP
        • LDAP Service Directory Mapping
      • OIDC
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
      • RBAC
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
  • Develop Custom Plugins
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
    • Plugin Development Kit
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
    • Plugins in Other Languages
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
  • Kong Plugins
    • Overview
    • Authentication Reference
    • Allow Multiple Authentication Plugins
    • Plugin Queuing
      • Overview
      • Plugin Queuing Reference
  • Admin API
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • Status API
  • Reference
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • Key Management
    • Performance Testing Framework
    • The Expressions Language
      • Overview
      • Language References
      • Performance Optimizations
    • Rate Limiting Library
    • FAQ
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Prerequisites
  • PostgreSQL setup
    • mTLS
  • Kong Gateway TLS configuration
    • Kong Gateway mTLS configuration
  • Creating certificates
    • Intermediate CA chain
    • Chain without intermediate CA
    • Self-signed certificates for testing
You are browsing documentation for an older version. See the latest documentation here.

Configuring PostgreSQL TLS

Configuring TLS adds a layer of security to Kong Gateway by ensuring that all data transmitted between Kong Gateway and the PostgreSQL server is encrypted. There are some advantages and disadvantages to this approach:

  • Advantages:
    • Authentication: TLS can authenticate traffic between Kong Gateway and the PostgreSQL server. This helps prevent man-in-the-middle attacks. With TLS, Kong Gateway can verify that it is communicating with the correct PostgreSQL server, and the PostgreSQL server can verify that Kong Gateway or any other client is authorized to connect.
    • Encryption: The data that is transmitted between Kong Gateway and the PostgreSQL server is encrypted. This method protects your data from unauthorized access.
    • Data integrity: With TLS, your data is protected during transport.
  • Disadvantages:
    • Complexity: Configuring and maintaining secure TLS connections requires managing certificates and may add additional complexity to your Kong Gateway instance.
    • Performance: Encrypting and decrypting data consumes additional computing resources which can impact the performance of Kong Gateway.

This guide shows you how to configure TLS on PostgreSQL and Kong Gateway to secure your data in transport.

Prerequisites

  • OpenSSL
  • TLS support enabled in PostgreSQL.
    • If you are installing a pre-packaged distribution, or using the official Docker image, TLS support is already included.
    • If you are compiling PostgreSQL from source, TLS support must be enabled at build time using the --with-ssl=openssl flag. In this case, the OpenSSL development package needs to be installed as well.

PostgreSQL setup

To set up the PostgreSQL server with TLS enabled, configure the following parameters in the postgresql.conf file:

ssl = on #This parameter tells PostgreSQL to start with `ssl`. 
ssl_cert_file = '/path/to/server.crt' # If this parameter isn't specified, the cert file must be named `server.crt` in the server's data directory. 
ssl_key_file = '/path/to/server.key' # This is the default directory, other locations and parameters can be specified. 

With these settings, the server can establish a secure communication channel with a client using TLS. If the client supports TLS, the server proceeds with the TLS handshake and establishes a secure connection. In the case where a client does not support SSL or TLS, the system will fall back on an unsecured connection.

The key files that are referenced in the PostgreSQL configuration must have the right permissions. If the file is owned by the database user, it must be set to u=rw (0600). Set this using the following command:

chmod 0600 /path/to/server.key

If the file is owned by the root user, the permissions for the file must be u=rw,g=r (0640). Set this using the following command:

chmod 0640 /path/to/server.key.

Certificates issued by intermediate certificate authorities can also be used, but the first certificate in server.crt must be the server’s certificate, and it must match the server’s private key.

mTLS

Mutual Transport Layer Security (mTLS) is a protocol that provides an additional layer of security on top of the standard TLS protocol. mTLS requires that both the client and the server authenticate each other during the TLS handshake. If you require PostgreSQL to use mTLS authentication, there are mTLS specific parameters that must be set.

ssl_ca_file = '/path/to/ca/chain.crt'

This parameter must be set to the file that contains the trusted certificate authority. By default, this only verifies against the configured certificate authority if a certificate is present. There are two approaches to enforcing client certificates during login: cert authentication and clientcert authentication.

cert authentication method

The cert authentication method uses SSL client certificates to perform authentication. For this method, edit the hostssl line in the pg_hba.conf:

hostssl all all all cert

The cert authentication method enforces that a certificate is valid, and also ensures that the Common Name (cn) in the certificates matches the username or an applicable mapping of the requested database.

Username mapping can be used to allow the cn to be different from the username in the database. You can learn more about username mapping in the PostgreSQL official Username mapping docs.

clientcert authentication option

The clientcert authentication option can combine any authentication method for hostssl entries with the verification of a client certificate. This allows the server to enforce that the certificate is valid and ensure that the cn in the certificate matches the username or the appropriate mapping.

To use clientcert authentication, set the hostssl line in the pg_hba.conf file to the following:

hostssl all all all trust clientcert=verify-full

With this setting, PostgreSQL allows any client to connect to the server over SSL/TLS, and the server can trust the client without asking for a password or other form of authentication. The server verifies the client certificate to ensure that the certificate is valid and the cn on the certificate matches the correct mapping in the database.

In both methods, the Certificate Revocation List (CRL) is also checked when a client connects to the server if the parameter ssl_crl_file is set. The CRL is used to revoke invalid certificates.

Kong Gateway TLS configuration

To configure TLS on Kong Gateway, add the following settings to the kong.conf configuration file:

pg_ssl = on
pg_ssl_required = on
pg_ssl_verify = on
pg_ssl_version = tlsv1_2
lua_ssl_trusted_certificate = system,/path/to/ca/chain.crt
lua_ssl_verify_depth = 1

For more information about these parameters, see the Kong Gateway PostgreSQL settings documentation, as well as the specific documentation for lua_ssl_trusted_certificate and lua_ssl_verify_depth.

Kong Gateway mTLS configuration

If mTLS is required, Kong Gateway needs to be provide a certificate to the PostgreSQL server during the handshake process. This can be accomplished by adding the following settings to kong.conf:

pg_ssl_cert = '/path/to/client.crt'
pg_ssl_cert_key = '/path/to/client.key'
  • pg_ssl_cert The absolute path to the PEM-encoded client TLS certificate for the PostgreSQL connection. Mutual TLS authentication against PostgreSQL is only enabled if this value is set.

  • pg_ssl_cert_key If pg_ssl_cert is set, the absolute path to the PEM-encoded client TLS private key for the PostgreSQL connection.

The client certificate must be trusted by one of the specified certificate authorities. The certificate authorities are set in the ssl_ca_file parameter in the PostgreSQL configuration file postgres.conf.

Creating certificates

Certificates can be created with OpenSSL using the default settings.

Intermediate CA chain

An intermediate CA chain means the server or the client certificates are issued by an intermediate CA, not issued directly by the root CA.

From the terminal, generate a root CA private key and self-sign a root CA certificate using these steps:

  1. Generate a root CA cert-key pair:

     openssl req -new -x509 -utf8 -nodes -subj "/CN=root.yourdomain.com" -config /etc/ssl/openssl.cnf -extensions v3_ca -days 3650 -keyout root.key -out root.crt
    
  2. Generate an intermediate private key and certificate:
    1. Generate the CA private key and certificate signing request (CSR):
       openssl req -new -utf8 -nodes -subj "/CN=intermediate.yourdomain.com" -config /etc/ssl/openssl.cnf -keyout intermediate.key -out intermediate.csr
      
    2. Change the private key permissions:
       chmod og-rwx intermediate.key
      
    3. Create an intermediate CA certificate signed by the root CA:
       openssl x509 -req -extfile /etc/ssl/openssl.cnf -extensions v3_ca -in intermediate.csr -days 1825 -CA root.crt -CAkey root.key -CAcreateserial -out intermediate.crt
      
  3. Generate the server private key and certificate:
    1. Generate a server private key and certificate signing request (CSR):
       openssl req -new -utf8 -nodes -subj "/CN=dbhost.yourdomain.com" -config /etc/ssl/openssl.cnf -keyout server.key -out server.csr
      
    2. Change the permissions of the private key:
       chmod og-rwx server.key
      
    3. Create a server certificate signed by the intermediate CA:
       openssl x509 -req -in server.csr -days 365 -CA intermediate.crt -CAkey intermediate.key -CAcreateserial -out server.crt
      
  4. Generate a private key and certificate for the client:
    1. Generate a client private key and certificate signing request (CSR):
      openssl req -new -utf8 -nodes -subj "/CN=kong" -config /etc/ssl/openssl.cnf -keyout client.key -out client.csr
      
    2. Change the permissions of the private key:
      chmod og-rwx client.key
      
    3. Create a client certificate signed by an intermediate CA:
       openssl x509 -req -in client.csr -days 365 -CA intermediate.crt -CAkey intermediate.key -CAcreateserial -out client.crt
      
  5. Append the certificates:
    1. Complete the CA chain:
       cat intermediate.crt > chain.crt
       cat root.crt >> chain.crt
      
    2. Optional: append intermediate.crt to server.crt:
       cat intermediate.crt >> server.crt
      

      This step is typically done when the server is configured to use a certificate chain that includes the intermediate CA. If the server is not configured to use a certificate chain, or if the intermediate CA is already included in the server.crt file, this step is not necessary.

    3. Optional: append intermediate.crt to client.crt:
       cat intermediate.crt >> client.crt
      

      This step is typically done when the client is configured to use a certificate chain that includes the intermediate CA. If the client is not configured to use a certificate chain, or if the intermediate CA is already included in the client.crt file, this step is not necessary.

Chain without intermediate CA

In some cases, the certificate chain can be signed directly by the root certificate authority instead of an intermediate CA. This type of chain may be used in situations where the certificate is issued by a well-known and trusted root CA, and the level of security and trust provided by an intermediate CA is not necessary.

Important: Not using an intermediate CA can be less secure than using an intermediate CA, because the chain is shorter, and there are no additional layers of security that would normally be provided by the intermediate CA.

  1. Generate a root CA cert key pair:

     openssl req -new -x509 -utf8 -nodes -subj "/CN=root.yourdomain.com" -config /etc/ssl/openssl.cnf -extensions v3_ca -days 3650 -keyout root.key -out root.crt
    
  2. Generate server private key and certificate:
    1. Generate a server private key and certificate signing request (CSR):
       openssl req -new -utf8 -nodes -subj "/CN=dbhost.yourdomain.com" -config /etc/ssl/openssl.cnf -keyout server.key -out server.csr
      
    2. Change the permissions of the private key:
       chmod og-rwx server.key
      
    3. Create a server certificate signed by the intermediate CA:
       openssl x509 -req -in server.csr -days 365 -CA root.crt -CAkey root.key -CAcreateserial -out server.crt
      
  3. Generate a private key and certificate for the client:
    1. Generate a client private key and certificate signing request (CSR):
      openssl req -new -utf8 -nodes -subj "/CN=kong" -config /etc/ssl/openssl.cnf -keyout client.key -out client.csr
      
    2. Change the permissions of the private key:
      chmod og-rwx client.key
      
    3. Create a client certificate signed by an intermediate CA:
       openssl x509 -req -in client.csr -days 365 -CA root.crt -CAkey root.key -CAcreateserial -out client.crt
      

      Self-signed certificates for testing

Self-signed certificates should only be used for testing.

  1. Generate server key and self-signed cert:

    openssl req -new -x509 -utf8 -nodes -subj "/CN=dbhost.yourdomain.com" -config /etc/ssl/openssl.cnf -days 365 -keyout server.key -out server.crt
    
  2. Change private key permissions:
     chmod og-rwx server.key
    
  3. Generate the client key and self-signed certificate:
     openssl req -new -x509 -utf8 -nodes -subj "/CN=kong" -config /etc/ssl/openssl.cnf -days 365 -keyout client.key -out client.crt
    
  4. Change the permissions of the private key:
     chmod og-rwx client.key
    

When you use a self-signed certificate, the client.crt should be specified in the ssl_ca_file parameter, and the server.crt should be specified in the lua_ssl_trusted_certificate parameter.

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
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025