You are browsing documentation for an older version. See the latest documentation here.

Using mtls-auth plugin

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

Before you begin ensure that you have Installed Kong Ingress Controller in your Kubernetes cluster and are able to connect to Kong. This guide requires Kong Gateway Enterprise.

Prerequisites

Install Kong

You can install Kong in your Kubernetes cluster using Helm.

Add the Kong Helm charts:

 helm repo add kong https://charts.konghq.com
 helm repo update

Create a file named license.json containing your Kong Gateway Enterprise license and store it in a Kubernetes secret:

 kubectl create namespace kong
 kubectl create secret generic kong-enterprise-license --from-file=license=./license.json -n kong

Create a values.yaml file:

 gateway:
   image:
     repository: kong/kong-gateway
   env:
     LICENSE_DATA:
       valueFrom:
         secretKeyRef:
           name: kong-enterprise-license
           key: license

Install Kong Ingress Controller and Kong Gateway with Helm:

 helm install kong kong/ingress -n kong --create-namespace --values ./values.yaml

Test connectivity to Kong

Kubernetes exposes the proxy through a Kubernetes service. Run the following commands to store the load balancer IP address in a variable named PROXY_IP:

Populate $PROXY_IP for future commands:

 export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
 echo $PROXY_IP

Ensure that you can call the proxy IP:

 curl -i $PROXY_IP

The results should look like this:

 HTTP/1.1 404 Not Found
 Content-Type: application/json; charset=utf-8
 Connection: keep-alive
 Content-Length: 48
 X-Kong-Response-Latency: 0
 Server: kong/3.0.0
  
 {"message":"no Route matched with those values"}

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"

Add the generated certificates to Kong.
CA certificates in Kong are provisioned by creating a Secret resource in Kubernetes.

CA certificate secrets must have the following properties:
- the konghq.com/ca-cert: "true" label applied.
- acert 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
```

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

Install an echo service that will be secured using TLS client certificate authentication:

$ 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

Create an Ingress to expose the echo service outside the Kubernetes cluster:

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

The results should look like this:

 ingress.extensions/demo created

Test the configuration

Send a request to check Kong prompts you for client certificate.
```
 $ curl -i -k https://$PROXY_IP/test
```
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.

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

 $ curl --key key.pem --cert cert.pem  https://$PROXY_IP/test -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