You are browsing unreleased documentation. See the latest documentation here.

mTLS

Configure the Kong Ingress Controller to verify client certificates using CA certificates and mtls-auth plugin for HTTPS requests.

1. Generate self-signed CA certificates using OpenSSL:

    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes \
    -subj "/C=US/ST=California/L=San Francisco/O=Kong/OU=Org/CN=www.example.com"
   

2. Add the generated certificates to Kong.

   CA certificates in Kong are provisioned by creating Secret or ConfigMap resource in Kubernetes. Resources holding CA certificates must have the following properties:

   • the konghq.com/ca-cert: "true" label applied.
   • a cert or ca.crt data property which contains a valid CA certificate in PEM format.
   • a kubernetes.io/ingress.class annotation whose value matches the value of the controller’s --ingress-class argument. By default, that value is kong.
   • an id data property which contains a random UUID.

   Each CA certificate that you create needs a unique ID. Any random UUID should suffice here and it doesn’t have a security implication. You can use uuidgen (Linux, OS X) or New-Guid (Windows) to generate an ID.

    $ kubectl create secret generic my-ca-cert --from-literal=id=cce8c384-721f-4f58-85dd-50834e3e733a --from-file=cert=./cert.pem
    $ kubectl label secret my-ca-cert 'konghq.com/ca-cert=true'
    $ kubectl annotate secret my-ca-cert 'kubernetes.io/ingress.class=kong'
   

   The results should look like this:

    secret/my-ca-cert created
    secret/my-ca-cert labeled
    secret/my-ca-cert annotated
   

3. Configure mtls-auth KongPlugin resource which references the CA certificate. Make sure that the ID matches the ID provided in your kubectl create secret command:

    $ echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: mtls-auth
    config:
      ca_certificates:
      - cce8c384-721f-4f58-85dd-50834e3e733a
      skip_consumer_lookup: true
      revocation_check_mode: SKIP
    plugin: mtls-auth
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/mtls-auth created
   

Deploy an echo service

To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:

kubectl apply -f https://docs.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml

The results should look like this:

service/echo created
deployment.apps/echo created

Add routing configuration

Create routing configuration to proxy /echo requests to the echo server:

echo "
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /echo
    backendRefs:
    - name: echo
      kind: Service
      port: 1027
" | kubectl apply -f -

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027
" | kubectl apply -f -

The results should look like this:

httproute.gateway.networking.k8s.io/echo created

ingress.networking.k8s.io/echo created

Test the routing rule:

curl -i $PROXY_IP/echo

The results should look like this:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 140
Connection: keep-alive
Date: Fri, 21 Apr 2023 12:24:55 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.2.2

Welcome, you are connected to node docker-desktop.
Running on Pod echo-7f87468b8c-tzzv6.
In namespace default.
With IP address 10.1.0.237.
...

If everything is deployed correctly, you should see the above response. This verifies that Kong Gateway can correctly route traffic to an application running inside Kubernetes.

Add the konghq.com/plugin annotation

kubectl annotate httproute echo konghq.com/plugins='mtls-auth'

kubectl annotate ingress echo konghq.com/plugins='mtls-auth'

Test the configuration

1. Send a request to check Kong prompts you for client certificate.

    $ curl -i -k https://$PROXY_IP/echo
   

   The results should look like this:

    HTTP/2 401
    content-type: application/json; charset=utf-8
    content-length: 50
    x-kong-response-latency: 0
    server: kong/2.0.4.0-enterprise-k8s
   
    {"message":"No required TLS certificate was sent"}
   

   As you can see, Kong is restricting the request because it doesn’t have the necessary authentication information.

   Two things to note here:

   • -k is used because Kong is set up to serve a self-signed certificate by default. For full mutual authentication in production use cases, you must configure Kong to serve a certificate that is signed by a trusted CA.
   • For some deployments $PROXY_IP might contain a port that points to http port of Kong. In others, it might happen that it contains a DNS name instead of an IP address. If needed, update the command to send an https request to the https port of Kong or the load balancer in front of it.

2. Use the key and certificate to authenticate against Kong and use the service:

    $ curl --key key.pem --cert cert.pem  https://$PROXY_IP/echo -k -I
   

   The results should look like this:

    HTTP/2 200
    content-type: text/plain; charset=UTF-8
    server: echoserver
    x-kong-upstream-latency: 1
    x-kong-proxy-latency: 1
    via: kong/2.0.4.0-enterprise-k8s