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'
```
Copied to clipboard!

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

Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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"
     }')

Copied to clipboard!

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://";"")')

Copied to clipboard!

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

Copied to clipboard!

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

Copied to clipboard!

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'"
     }'

Copied to clipboard!

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

Copied to clipboard!

Kong Ingress Controller running (attached to Konnect)

Add the Kong Helm charts:

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

Copied to clipboard!

Create a values.yaml file:

cat <<EOF > values.yaml
controller:
  ingressController:
    image:
      tag: "3.4"
    env:
      feature_gates: "FillIDs=true"
    konnect:
      license:
        enabled: true
      enabled: true
      controlPlaneID: "$CONTROL_PLANE_ID"
      tlsClientCertSecretName: konnect-client-tls
      apiHostname: "us.kic.api.konghq.com"
gateway:
  image:
    repository: kong/kong-gateway
  env:
    konnect_mode: 'on'
    vitals: "off"
    cluster_mtls: pki
    cluster_telemetry_endpoint: "$CONTROL_PLANE_TELEMETRY:443"
    cluster_telemetry_server_name: "$CONTROL_PLANE_TELEMETRY"
    cluster_cert: /etc/secrets/konnect-client-tls/tls.crt
    cluster_cert_key: /etc/secrets/konnect-client-tls/tls.key
    lua_ssl_trusted_certificate: system
    proxy_access_log: "off"
    dns_stale_ttl: "3600"
  secretVolumes:
     - konnect-client-tls
EOF

      
        
      
    
Copied to clipboard!

Install Kong Ingress Controller using Helm:

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

Copied to clipboard!

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

Copied to clipboard!

Kong Ingress Controller running

Add the Kong Helm charts:

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

Copied to clipboard!

Install Kong Ingress Controller using Helm:

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

Copied to clipboard!

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

Copied to clipboard!

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

Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

 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 -

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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

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

Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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"
   }]'

      
        
      
    
Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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

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

Copied to clipboard!

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

Copied to clipboard!

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 -

      
        
      
    
Copied to clipboard!

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

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

Copied to clipboard!

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

Copied to clipboard!

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"

Copied to clipboard!

my-user can access /secured-endpoint:

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

Copied to clipboard!

my-admin can access /sensitive-endpoint:

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

Copied to clipboard!

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

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

Copied to clipboard!

You should see the following response:

 You cannot consume this service

Copied to clipboard!

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

Copied to clipboard!