See what makes Kong the fastest, most-adopted API gateway
Check out the latest Kong feature releases and updates
Single platform for SaaS end-to-end connectivity
Enterprise service mesh based on Kuma and Envoy
Collaborative API design platform
How to Scale High-Performance APIs and Microservices
Call for speakers & sponsors, Kong API Summit 2023!
5 MIN READ
Like many developers and operations professionals, you may have had complicated experiences with security and certificates (encryption of the connection and authentication). Maybe so much so that you try to avoid working on them whenever possible.
If you’re looking for a simpler way, Kong may be the answer. As with everything with Kong, the idea is to make things as lightweight as possible, including the complexity of setting up and maintaining certificate-based security.
For more on this API security, check out our “Security in a Multi-Cloud World” eBook
One of our global customers in the banking industry recently had a mature certificate infrastructure that needed adoption from internal and governmental regulations. Based on their previous experience with legacy gateways, they were afraid of the complexity of integrating the gateway into their certificate management system and making sure updates are propagated automatically to the gateway cluster. In their previous solution, this was a manual task. With the below Kong mTLS use cases, this was quick and easy.
When thinking about certificates in an API gateway context, you might immediately think about these two use cases:
But there are two more use cases you may want to consider:
Let’s start with the certificate Kong serves to the client (the one you would see when opening the proxy in the browser).
When someone accesses a route exposed using Kong Gateway, the presented certificate by Kong should match the entered hostname (for example, proxy.example.com) so the client can trust that Kong established the connection.
The default certificate presented by Kong after installation is a self-signed certificate. If you want to change this default, copy your desired certificate and key on the machine and then set ssl_cert and ssl_cert_key in your /etc/kong/kong.conf.
Example:
/etc/kong/kong.conf: (...) ssl_cert = /etc/secrets/my-kong-certificate/kong.crt ssl_cert_key = /etc/secrets/my-kong-certificate/kong.key (...)
But what if Kong is listening on multiple different hostnames/FQDN? In this case, we need to present different certificates depending on the route. Examples might be different brandings (like api.myshoesbrand.com and api.myshirtsbrand.com) or also very common internal vs. external phasing routes (like api.interal.lan and api.mybrand.com).
When looking at the route object, we notice the hosts parameter that we can use to limit the hosts being listened on and the snis parameter (SNI stands for “server name indication“).
Example on how to create a route for a specific hostname:
http -f admin.kong.internal.lan/services/myservice/routes name=myRoute hosts=api.internal.lan
But how do we define an SNI and which certificates it shall use? Well, you might have guessed it already. There is an API for that: SNI API endpoint.
Now that we attached an SNI to a route, how do we add the certificate to the SNI? There’s an API to upload a certificate.
The actual order is the exact opposite of how we just went through it:
If you want to automate the whole process using Let’s Encrypt, look at the ACME plugin that integrates Kong with Let’s Encrypt to create and auto-update certificates. We won’t cover the details of this, as the Let’s Encrypt setup is out of scope for this blog post.
Technical Guide: Secure Your Web, Mobile Applications and APIs using the Kong Gateway
Note: While all the other documentation here is true for both Kong and Kong Enterprise, mTLS is an enterprise-only plugin.
Authenticating consumers based on certificates is a prevalent mechanism, especially for (but not limited to) financial users of Kong. Each client gets its own certificate to present on every API call to prove its identity.
The mTLS plugin has one parameter called ca_certificates. As the name already tells us, we need to specify one or multiple CAs, which we’ll use as the trusted source. Only incoming certificates that use those CAs will be trusted.
And similar to the above, we need to upload those CAs in advance using the ca_certificates API endpoint.
Uploading a CA to Kong is achieved with:
http -f admin.kong.internal.lan/ca_certificates cert@the_ca_file_on_your_harddisk.pem
When we have uploaded the certificate, we can now reference it when configuring the mTLS-auth plugin, for example:
http -f admin.kong.internal.lan/services/myservice/mTlsRoute hosts=cert-only.example.com name=mtls http -f admin.kong.internal.lan/routes/mTlsRoute/plugins config:="{\"ca_certificates\": [\"THE_CERT_ID_YOU_GOT_FROM_UPLOAD_ABOVE\"]"
Now that we authenticated the incoming certificate, how do we make sure not every certificate issued by the CA is allowed to make the call?
For this, the mTLS plugin provides two parameters:
The trust between the gateway and the backend system can be secured using certificates. This time, Kong presents a certificate to the upstream to prove its identity. This use case is about the backend validating that an accepted incoming call came from Kong Gateway and not another intermediary.
Kong presents a self-signed certificate (the default) after installation to the upstream. If you want to change this default:
/etc/kong/kong.conf: (...) client_ssl = on client_ssl_cert = /etc/secrets/my-kong-certificate/kong.crt client_ssl_cert_key = /etc/secrets/my-kong-certificate/kong.key (...)
Sometimes we need to present different certificates to different upstreams to override the default certificate on a per-service level.
We can use the service object client_certificate parameter to specify the presented certificate.
As discussed above, check out the API to upload a certificate.
Attach the certificate to all calls for a specific service (the id got returned from the previous call) http -f admin.kong.internal.lan/services/my_sensitive_backend url=https://sensitive.internal.lan client_certificate.id=the_id_from_previous_upload
We can limit the trusted certificates Kong expects from the upstreams by changing the lua_ssl_trusted_certificate. This is used when Kong Gateway is sure that the connected backend is connected and there’s no service in the middle. We’re achieving two-way mutual trust in combination with the above #3.
/etc/kong/kong.conf: (...) lua_ssl_trusted_certifcate = /etc/secrets/my-kong-certificate/kong.crt (...)
Certificates can play a vital role in the trusted connections to your clients and your backend systems. Using them, you can achieve both the encryption of the traffic on the transport level and create (mutual) trust between the connected systems.
Certificate configurations can often be very complex. Handling all of this within Kong keeps it simple. It can be integrated into existing certificate management systems to automate all the configurations.
Try out these examples yourself by getting a Kong installation. If you have any questions, do not hesitate to contact us.
Share Post
Learn how to make your API strategy a competitive advantage.