Kong Gateway Introduction - mTLS Support

Security in API communication is extremely important for maintaining system reliability. This article provides a detailed explanation of how to configure mTLS (Mutual TLS) using Kong API Gateway. In particular, it covers how to set up mTLS for the two communication paths: “Client -> Kong” and “Kong -> Upstream API”.

Basics of mTLS

mTLS is an extension of TLS (Transport Layer Security) in which both sides of the communication (client and server) authenticate each other using certificates. While regular TLS only authenticates the server, mTLS adds the following processes:

1. Server authentication: The client verifies that the server has a trusted certificate.
2. Client authentication: The server verifies that the client has a trusted certificate.

This bidirectional authentication enables more secure communication.

Achieving mTLS Communication with Kong API Gateway

With Kong API Gateway, you can easily implement mTLS on the following two communication paths:

• Client → Kong API Gateway
• Kong API Gateway → Upstream API

mTLS Settings for Client->Kong

To implement mTLS for communication from the client to Kong API Gateway, use Kong’s “mTLS Plugin”. The steps are as follows:

1. The administrator sets the CA certificate for client authentication in Kong
2. The client presents its own certificate to Kong when making a request
3. Kong verifies the client certificate and allows secure communication

Register the CA Certificate

Register the CA certificate in Kong to verify the client’s certificate

1
2
3
4
5
6
7
8
9

curl http://localhost:8001/ca_certificates -F cert=@ca.crt

{
  "cert": "<PEM_CERT>",
  "id": "c383d81a-bffc-4e2a-b0d3-ac56b441a07b",
  "cert_digest": "3e9099b5015e8f486c00bcea9d111ee721faba355a89bcf1df69561e3dc6325c",
  "tags": null,
  "created_at": 1607347576
}

Enable the mTLS Plugin

Enable the mTLS plugin using the ca_certificate created above. Here, it is specified at the global scope.

1
2
3
4
5

curl --request POST \
  --url http://localhost:8001/plugins \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data name=mtls-auth \
  --data config.ca_certificates=c383d81a-bffc-4e2a-b0d3-ac56b441a07b

At this point, if you try to access without a client certificate, you should get an HTTP/1.1 401 Unauthorized error.

Access with a Client Certificate

Since mTLS means mutual TLS authentication, you must use the HTTPS protocol when accessing. If Kong’s TLS certificate is self-signed, you may need to add the -k flag to skip certificate verification.

1

curl https://<PROXY_URL>:8443/mtls --key client.key --cert client.crt -k

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 752
Content-Type: application/json
Date: Fri, 20 Dec 2024 15:14:38 GMT
Server: gunicorn/19.9.0
Via: 1.1 kong/3.9.0.0-enterprise-edition
X-Kong-Proxy-Latency: 9
X-Kong-Request-Id: ada6f204577fe50a144706292a01f421
X-Kong-Upstream-Latency: 8

{
    "args": {},
    "data": "",
    "files": {},
    "form": {},
    "headers": {
        "Accept": "*/*",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive",
        "Host": "httpbin.backends:8080",
        "Kong-Request-Id": "e8560956-1bdf-491b-aa05-f962db06adcd",
        "User-Agent": "HTTPie/3.2.4",
        "X-Consumer-Custom-Id": "[email protected]",
        "X-Consumer-Id": "35cfdf1b-11ef-4582-b80f-a0cfb1d67b07",
        "X-Consumer-Username": "[email protected]",
        "X-Forwarded-Host": "localhost",
        "X-Forwarded-Path": "/mtls-auth",
        "X-Forwarded-Prefix": "/mtls-auth",
        "X-Kong-Request-Id": "ada6f204577fe50a144706292a01f421"
    },
    "json": null,
    "method": "GET",
    "origin": "192.168.65.1",
    "url": "https://localhost/anything"
}

mTLS Settings for Kong->Upstream API

When Kong accesses the API, the Upstream API requires a client certificate. Therefore, you need to register a client certificate on the Kong side. There are two ways to register: globally for Kong, or per Service.

Register Globally for Kong

Add the following three parameters to the configuration file. When Kong sends a request to the API, it will also send the client certificate.

1
2
3

client_ssl = on
client_ssl_cert = /etc/secrets/my-kong-certificate/kong.crt
client_ssl_cert_key = /etc/secrets/my-kong-certificate/kong.key

Register Per Service

When creating a Service, you can add a client certificate with client_certificate. The priority is: per Service > global. If both are set, the Service setting takes precedence.

Conclusion

By properly configuring mTLS, you can greatly enhance the security of API communication. This article introduced how to set up mTLS for the two communication paths: “Client -> Kong” and “Kong -> Upstream API”.

To ensure secure API communication, keep the following points in mind:

• Properly manage the CA certificate for client authentication
• Correctly configure the client certificate between Kong and the Upstream API
• Use global or per-Service settings as appropriate

Refer to the diagrams and try introducing mTLS in your own environment.