ACL

Uses: Kong Ingress Controller

Deployment Platform:

Prerequisites

Kong Konnect

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Set the personal access token as an environment variable:
```
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
```

Enable the Gateway API (Optional)

Install the Gateway API CRDs before installing Kong Ingress Controller.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

Create a Gateway and GatewayClass instance to use.

echo "
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'
spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
         from: All
" | kubectl apply -n kong -f -

Create a KIC Control Plane

Use the Konnect API to create a new CLUSTER_TYPE_K8S_INGRESS_CONTROLLER Control Plane:

CONTROL_PLANE_DETAILS=$(curl -X POST "https://us.api.konghq.com/v2/control-planes" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "My KIC CP",
       "cluster_type": "CLUSTER_TYPE_K8S_INGRESS_CONTROLLER"
     }')

We’ll need the id and telemetry_endpoint for the values.yaml file later. Save them as environment variables:

CONTROL_PLANE_ID=$(echo $CONTROL_PLANE_DETAILS | jq -r .id)
CONTROL_PLANE_TELEMETRY=$(echo $CONTROL_PLANE_DETAILS | jq -r '.config.telemetry_endpoint | sub("https://";"")')

Create mTLS certificates

Kong Ingress Controller talks to Konnect over a connected secured with TLS certificates.

Generate a new certificate using openssl:

openssl req -new -x509 -nodes -newkey rsa:2048 -subj "/CN=kongdp/C=US" -keyout ./tls.key -out ./tls.crt

The certificate needs to be a single line string to send it to the Konnect API with curl. Use awk to format the certificate:

export CERT=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' tls.crt);

Next, upload the certificate to Konnect:

curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/dp-client-certificates" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "cert": "'$CERT'"
     }'

Finally, store the certificate in a Kubernetes secret so that Kong Ingress Controller can read it:

kubectl create namespace kong -o yaml --dry-run=client | kubectl apply -f -
kubectl create secret tls konnect-client-tls -n kong --cert=./tls.crt --key=./tls.key

Kong Ingress Controller running

Add the Kong Helm charts:

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

Install Kong Ingress Controller using Helm:

helm install kong kong/ingress -n kong --create-namespace

Set $PROXY_IP as an environment variable for future commands:

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

Required Kubernetes resources

This how-to requires some Kubernetes services to be available in your cluster. These services will be used by the resources created in this how-to.

kubectl apply -f https://developer.konghq.com/manifests/kic/echo-service.yaml -n kong

This how-to also requires 2 pre-configured routes:

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

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

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

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

How the ACL plugin works

The ACL plugin compares a list of required groups on a Gateway Service or Route entity with the list of groups listed in an ACL credential that is attached to a Consumer. If the Consumer doesn’t have the required group, the request is denied.

There are two distinct concepts with the ACL name:

The ACL plugin, which contains a list of groups a Service or Route requires
The ACL credential, which contains a list of groups a Consumer is in

Both of these entities must be configured for the ACL plugin to work.

Provision consumers

Because the ACL plugin is attached to a Consumer, we need two Consumers added to Kong Gateway to demonstrate how the ACL plugin works. These Consumers will use the Key Authentication plugin to identify the Consumer from the incoming request.

Create secrets to add key-auth credentials for my-admin and my-user:

echo '
apiVersion: v1
kind: Secret
metadata:
  name: my-admin-key-auth
  namespace: kong
  labels:
    konghq.com/credential: key-auth
stringData:
  key: my-admin-password
---
apiVersion: v1
kind: Secret
metadata:
  name: my-user-key-auth
  namespace: kong
  labels:
    konghq.com/credential: key-auth
stringData:
  key: my-user-password
' | kubectl apply -f -

Create two Consumers that are identified by these secrets:

 echo "
 apiVersion: configuration.konghq.com/v1
 kind: KongConsumer
 metadata:
   name: my-admin
   namespace: kong
   annotations:
     kubernetes.io/ingress.class: kong
 username: my-admin
 credentials:
 - my-admin-key-auth
 " | kubectl apply -f -

 echo "
 apiVersion: configuration.konghq.com/v1
 kind: KongConsumer
 metadata:
   name: my-user
   namespace: kong
   annotations:
     kubernetes.io/ingress.class: kong
 username: my-user
 credentials:
 - my-user-key-auth
 " | kubectl apply -f -

Secure the service

The Key Auth plugin must be added to a Service or Route to identify the Consumer from the incoming request. Add the key-auth plugin to the echo Service:

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: key-auth
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
plugin: key-auth
" | kubectl apply -f -

Next, apply the KongPlugin resource by annotating the service resource:

kubectl annotate -n kong service echo konghq.com/plugins=key-auth

Create ACL credentials

The Key Auth plugin and other Kong Gateway authentication plugins only provide authentication, not authorization. They can identify a Consumer, and reject any unidentified requests, but not restrict which Consumers can access which protected URLs. Any Consumer with a key auth credential can access any protected URL, even when the plugins for those URLs are configured separately.

To provide authorization, or restrictions on which Consumers can access which URLs, you need to also add the ACL plugin, which can assign groups to Consumers and restrict access to URLs by group.

Create two plugins, one which allows only an admin group, and one which allows both admin and user.

Generate ACL credentials for both Consumers:

echo '
apiVersion: v1
kind: Secret
metadata:
  name: admin-acl
  namespace: kong
  labels:
    konghq.com/credential: acl
stringData:
  group: admin
---
apiVersion: v1
kind: Secret
metadata:
  name: user-acl
  namespace: kong
  labels:
    konghq.com/credential: acl
stringData:
  group: user
' | kubectl apply -f -

Patch the Consumers:

 kubectl patch -n kong --type json kongconsumer my-admin \
   -p='[{
     "op":"add",
     "path":"/credentials/-",
     "value":"admin-acl"
   }]'
 kubectl patch -n kong --type json kongconsumer my-user \
   -p='[{
     "op":"add",
     "path":"/credentials/-",
     "value":"user-acl"
   }]'

Add access control

Based on our authorization policies, anyone can access /secured-endpoint, but only administrators can access /sensitive-endpoint.

Create an ACL plugin that allows requests from anyone in the admin or user groups to /secured-endpoint:

 echo "
 apiVersion: configuration.konghq.com/v1
 kind: KongPlugin
 metadata:
   name: anyone-acl
   namespace: kong
   annotations:
     kubernetes.io/ingress.class: kong
 plugin: acl
 config:
   allow:
   - admin
   - user
 " | kubectl apply -f -

Next, apply the KongPlugin resource by annotating the httproute or ingress resource:

kubectl annotate -n kong httproute secured-endpoint konghq.com/plugins=anyone-acl

kubectl annotate -n kong ingress secured-endpoint konghq.com/plugins=anyone-acl

Create an ACL plugin that allows requests from anyone in the admin group to /sensitive-endpoint:

 echo "
 apiVersion: configuration.konghq.com/v1
 kind: KongPlugin
 metadata:
   name: admin-acl
   namespace: kong
   annotations:
     kubernetes.io/ingress.class: kong
 plugin: acl
 config:
   allow:
   - admin
 " | kubectl apply -f -

Next, apply the KongPlugin resource by annotating the httproute or ingress resource:

kubectl annotate -n kong httproute sensitive-endpoint konghq.com/plugins=admin-acl

kubectl annotate -n kong ingress sensitive-endpoint konghq.com/plugins=admin-acl

Validate your configuration

Your Routes are now protected with the Key Auth and ACL plugins using the following logic:

If the apikey header is invalid, the key-auth plugin rejects the request
If the identified Consumer has the user group in the ACL credential, they can access /secured-endpoint
If the identified Consumer has the admin group in the ACL credential, they can access both /secured-endpoint and /sensitive-endpoint

Test the ACL plugin using the following requests:

my-admin can access /secured-endpoint:

 curl "$PROXY_IP/secured-endpoint" \
      -H "apikey:my-admin-password"

 curl "$PROXY_IP/secured-endpoint" \
      -H "apikey:my-admin-password"

my-user can access /secured-endpoint:

 curl "$PROXY_IP/secured-endpoint" \
      -H "apikey:my-user-password"

 curl "$PROXY_IP/secured-endpoint" \
      -H "apikey:my-user-password"

my-admin can access /sensitive-endpoint:

 curl "$PROXY_IP/sensitive-endpoint" \
      -H "apikey:my-admin-password"

 curl "$PROXY_IP/sensitive-endpoint" \
      -H "apikey:my-admin-password"

my-user can’t access /sensitive-endpoint:

 curl "$PROXY_IP/sensitive-endpoint" \
      -H "apikey:my-user-password"

You should see the following response:

 You cannot consume this service

 curl "$PROXY_IP/sensitive-endpoint" \
      -H "apikey:my-user-password"