Securing APIs With Kong and mTLS: Everything You Need to Know
Intro
As APIs become the backbone of modern applications—especially in the AI era, where ‘There is no AI without APIs,’ as stated by Augusto, Kong’s CEO—securing communication has never been more critical. When it comes to API authentication, mutual TLS offers a robust solution by verifying both client and server identities. Due to its high level of security, mTLS is often a requirement for API consumption across industries, with some services mandating its use to authenticate API consumers.
In my previous blog posts, I’ve explored mTLS with Kong from various perspectives. However, a comprehensive guide that holistically addresses implementing mTLS with Kong has been missing. I am hoping this post fills that gap, covering everything from mTLS fundamentals to Kong’s various roles in the API lifecycle, as well as best practices to confidently secure your APIs while meeting stringent compliance requirements.
TLS and mTLS
Before we dive into mTLS in Kong, let’s revisit what TLS and mTLS are.
What is TLS
TLS (Transport Layer Security) is a cryptographic protocol that ensures secure communication over a computer network. It operates at Layer 4 (the Transport Layer) of the OSI model. When a client initiates a connection to a server, it requests the server’s supported cipher suites and its digital certificate. A secure connection is established only when both parties agree on a cipher to encrypt the messages and the server’s certificate can be validated by chaining it to a trusted root certificate on the client’s machine. This process ensures the client can trust the server. TLS is the foundation of secure internet communication, protecting most of the traffic we rely on every day.
What is mTLS
mTLS (Mutual TLS) builds on TLS by introducing an additional layer of validation. This means on top of clients verifying server certificates, the server also verifies the client’s identity. During the TLS handshake, the server requests the client to provide a certificate, which it then validates. The server checks that the client certificate is signed by certain certificate authorities, has specific attributes (such as a valid Distinguished Name or Common Name), and is not revoked. In some high-security environments, organizations may even validate specific details like certificate serial numbers or require client certificates to be stored on hardware tokens for added protection. mTLS is commonly used in scenarios requiring heightened security, such as internal services, APIs, or systems handling sensitive data.
mTLS in Kong
As an API gateway, Kong sits between clients and backend API servers. It plays a crucial role in API authentication, ensuring that only legitimate clients can access backend services while blocking bad actors.
Kong as Server
When Kong acts as the resource server in the API request lifecycle, it validates client certificates to ensure that only trusted clients can access the APIs. To enable mTLS, you can simply enable Kong’s mTLS plugin. You can find my blog post about this plugin here.
The choice of load balancer is crucial for mTLS functionality. As we’ve mentioned earlier, TLS handshake happens at OSI network model layer 4, which means many modern Layer 7 load balancers (e.g., AWS ALB, Azure Application Gateway) cannot be used if mTLS is required.
Kong gives you the choice to either use an L4 load balancer to passthrough the TLS termination to Kong or breaking up the mTLS process. The API consumers can now terminate TLS with a L7 load balancer, the load balancer forwards the certificate in a specific header, and let Kong to complete the validation. You can find more details in my blog post How to Do mTLS With Kong Behind AWS Application Load Balancer.
Kong as Client
Kong acts as a client when communicating with external services. If the service requires client authentication, Kong can be configured to present a client certificate during the TLS handshake with the service. This ensures that the service can verify Kong’s identity, allowing Kong to establish the trusted connection.
mTLS to Backend API
There are two approaches to enabling mTLS with backend APIs.
Client Certificate Per Service
Kong supports presenting different client certificates to the different backend APIs. In this set up, users need to
- Create certificate objects for their client certificates.
- Associate certificate objects to the service/upstream objects.
When a client request reaches Kong, Kong presents the associated client certificate to the backend.
Global Client Certificate
In some use cases, you might want to use the same certificate for all your backend APIs or you simply want to avoid managing client certificate objects. To achieve this, configure the default client certificate via client_ssl, client_ssl_cert and client_ssl_cert_key in Kong deployment.
I recommend storing client certificates as certificate objects and associate each certificate to the service for three reasons:
- You have more control over which certificate to use.
- Certificate rotation does not require restarting Kong.
- You can utilize Kong Vault and store the client certificate in external secret stores like AWS Secrets Manager. This ensures certificates are not stored in Kong’s configuration, enhancing security.
mTLS to PostgreSQL
If mTLS is enabled on your PostgreSQL instance, Kong also supports mTLS with the PostgreSQL database. To enable it, simply specify the client certificate inpg_ssl_cert and pg_ssl_cert_key.
mTLS to IDP
Kong openid connect plugin supports multiple client authentication methods for the IDP token endpoint. If your IDP requires mutual tls (tls_client_auth
), the openid connect plugin also supports this method.
To configure this:
- Create a certificate object to store your client certificate.
- Reference the certificate object ID on the plugin config.tls_client_auth_cert_id.
mTLS for Admin API
When Kong is deployed with a PostgreSQL database, you have the Admin API interface to manage Kong entities. A common practise is to apply network restrictions to Admin API endpoint. If you have an Enterprise License, you can use RBAC tokens to secure the Admin API endpoint. In some scenario, mTLs is required to secure this endpoint.
Nginx Config
Kong does not provide an out of box solution for mTLS with Admin API endpoint. Luckily Kong supports injecting nginx directive. We can apply the nginx ssl_verify_client directive to the Admin API.
Simply add the following to your kong.conf
.
1 | nginx_admin_ssl_client_certificate=/path/to/root.pem |
Or use the following environment variables if you run Kong in a container:
1 | KONG_NGINX_ADMIN_SSL_CLIENT_CERTIFICATE=/path/to/root.pem |
Loopback
Another approach is to loopback the Admin API as a service exposed via Kong proxy. Then you can enable mTLS plugin on the Admin API service.
Personally, I do not recommend the loopback approach. In my opinion the Admin API endpoint should never be allowed to be accessed via client-facing endpoints. Nework restriction are one consideration, and polluting the monitoring data is another, as Admin API logs will appear in proxy logs simultaneously. This also risks leaking privileged credentials in proxy logs.
Summary
Hopefully This post provides a comprehensive overview of how mTLS works in Kong, helping you make the right decisions and approaches for securing your APIs.
Here are the key takeaways:
- Identify requirements.
- Understand what information the backend requires.
- Determine where TLS termination occurs and where mTLS is required, helping you decide on infrastructure needs.
- Implement access control.
- DO NOT use self-signed certificates:
- Self-signed certificates lack revocation checks.
- They pose significant security risks if certificate management is not handled properly.
- Keep your certificate secured.
- Utilize trusted security tools like AWS Secrets Manager to store certificates.
- Use Kong Vault to read certificates dynamically, ensuring Kong configurations remain clean and secret rotation is automated.
See you in the next one.