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

mTLS and API Gateway Use Cases

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:

1. The gateway should present a certificate to the client.
2. The gateway should authenticate a user/grant access based on the client’s mutual TLS (mTLS).

But there are two more use cases you may want to consider:

1. Kong presents the certificate to the backend (upstream).
2. Kong sends the trust to the upstream (which certificate/s we allow the backend to present).

#1: Certificate Presented by Kong to the Client

Let’s start with the certificate Kong serves to the client (the one you would see when opening the proxy in the browser).

The Default Certificate

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
(...)

Certificate Per Route

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:

1. Upload the certificate (I do expect you have created it already and have put the files into the current folder)
   http -f admin.kong.internal.lan/certificates cert=@myCert.crt key=@myCert.key tags=myCert
2. Create an SNI and link to the uploaded certificate (the above command created the id)
   http -f admin.kong.internal.lan/snis name=api.interal.lan certificate.id=the-certificate-id-you-got-from-above-upload
3. Create a route linking to the SNI (the above command created the id)
   http -f admin.kong.internal.lan/services/myservice/routes name=myInternalRoute hosts=api.internal.lan snis=the-sni-id-you-got-from-above-upload

Let’s Encrypt

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

#2: mTLS for Clients

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.  

Authentication

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\"]"

Authorization

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:

1. By default, the parameter skip_consumer_lookup is set to false, so there must be a matching consumer in Kong. If no consumer is found, the call gets denied. We can do all the typical consumer-based steps if we find a consumer, even adding the consumer to one or multiple groups using the ACL plugin.
2. Depending on the contents of your certificate, it already might contain group membership information (see parameter authenticated_group_by). If so, we can directly use those extracted groups with the ACL plugin even without consumer matching in place.

#3: Certificate Presented by Kong to the Upstream

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.

The Default Certificate

Kong presents a self-signed certificate (the default) after installation to the upstream. If you want to change this default: 

1. Copy your desired certificate and key to the machine.
2. Enable client_ssl. 
3. Set client_ssl_cert and client_ssl_cert_key in your /etc/kong/kong.conf.

Example:

/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
(...)

Certificate Per Service

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.

1. Upload the certificate (I do expect you have created it already and have put the files into the current folder)
   http -f admin.kong.internal.lan/certificates cert=@myCert.crt key=@myCert.key tags=myCert

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  

#4: Trusting the Upstream’s Certificate

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.

Example: 

/etc/kong/kong.conf:
(...)
lua_ssl_trusted_certifcate = /etc/secrets/my-kong-certificate/kong.crt
(...)

Conclusion

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.