Home / Kong Ingress Controller / How To
Edit
Report

ACL

Uses: Kong Ingress Controller
Deployment Platform
Related Documentation
All KIC Documentation
TL;DR

Create a Secret with a konghq.com/credential: acl label and apply it to the Consumer that you want to access the Service.

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

Update an existing consumer to uses these credentials:

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

Then apply the ACL plugin to the service you want to protect

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 service resource:

kubectl annotate -n kong service my-service konghq.com/plugins=admin-acl

Prerequisites

Kong Konnect

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

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

  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

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:

  1. The ACL plugin, which contains a list of groups a Service or Route requires
  2. 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.

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

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

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

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

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

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

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:

  1. my-admin can access /secured-endpoint:

     curl "$PROXY_IP/secured-endpoint" \
      --no-progress-meter --fail-with-body  \
      -H "apikey:my-admin-password"

  2. my-user can access /secured-endpoint:

     curl "$PROXY_IP/secured-endpoint" \
      --no-progress-meter --fail-with-body  \
      -H "apikey:my-user-password"

  3. my-admin can access /sensitive-endpoint:

     curl "$PROXY_IP/sensitive-endpoint" \
      --no-progress-meter --fail-with-body  \
      -H "apikey:my-admin-password"

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

     curl "$PROXY_IP/sensitive-endpoint" \
      --no-progress-meter --fail-with-body  \
      -H "apikey:my-user-password"

    You should see the following response:

     You cannot consume this service

Cleanup

Delete created Kubernetes resources

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

Did this doc help?

Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support