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.

Prerequisites: Install Kong Ingress Controller in your Kubernetes cluster and connect to Kong. This guide requires Kong Gateway Enterprise.

Prerequisites

Install Kong

You can install Kong in your Kubernetes cluster using Helm.

1. Add the Kong Helm charts:

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

2. 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
   

3. Create a values.yaml file:

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

4. 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:

1. 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
   

2. 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"}
   

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 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
   

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
   

4. 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
   

5. 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

1. 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.

2. 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