You are browsing unreleased documentation. See the latest documentation here.

Access Control List plugin

Configure the Kong ACL Plugin. To use the ACL Plugin you need at least one Authentication plugin. This example uses the JWT Auth Plugin.

Deploy an echo service

To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:

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

Add routing configuration

Create routing configuration to proxy /lemon requests to the echo server:

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

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

The results should look like this:

httproute.gateway.networking.k8s.io/lemon created

ingress.networking.k8s.io/lemon created

Test the routing rule:

curl -i $PROXY_IP/lemon

The results should look like this:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 140
Connection: keep-alive
Date: Fri, 21 Apr 2023 12:24:55 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.2.2

Welcome, you are connected to node docker-desktop.
Running on Pod echo-7f87468b8c-tzzv6.
In namespace default.
With IP address 10.1.0.237.
...

If everything is deployed correctly, you should see the above response. This verifies that Kong Gateway can correctly route traffic to an application running inside Kubernetes.

After the first route is working, create a second pointing to the same Service:

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

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

The results should look like this:

httproute.gateway.networking.k8s.io/lime created

ingress.networking.k8s.io/lime created

Add JWT authentication to the service

To add authentication in front of an API you just need to enable a plugin.

1. Create a KongPlugin resource.

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: app-jwt
    plugin: jwt
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/app-jwt created
   

2. Associate the plugin to the Ingress rules.

    kubectl annotate service echo konghq.com/plugins=app-jwt
   

   The results should look like this:

    service/echo annotated
   

   Any requests matching the proxying rules for /lemon and /lime now requires a valid JWT and the consumer for the JWT to be associate with the right ACL. Requests without credentials are rejected.

3. Send a request without the credentials.

    curl -i $PROXY_IP/lemon
   

   The results should look like this:

    HTTP/1.1 401 Unauthorized
    Date: Fri, 09 Dec 2022 23:51:35 GMT
    Content-Type: application/json; charset=utf-8
    Connection: keep-alive
    Content-Length: 26
    X-Kong-Response-Latency: 1
    Server: kong/3.0.1
   
    {"message":"Unauthorized"}
   

Provision consumers

To access the protected endpoints, create two consumers.

1. Create a consumer named admin:

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

   The results should look like this:

    kongconsumer.configuration.konghq.com/admin created
   

2. Create a consumer named user:

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

   The results should look like this:

    kongconsumer.configuration.konghq.com/user created
   

Provision JWT credentials

JWT is a standard for tokens stored in JSON. They include a metadata section about the algorithms used to construct the JWT, information (“claims”) about the token and its bearer, and a cryptographic signature that recipients can use to verify the validity of the token.

When generating tokens ensure that the payload data contains a field named iss alongside name and iat. For the admin token you should set "iss": "admin-issuer" and for the user token you should set "iss": "user-issuer".

As valid JWTs are not easily constructed by hand, you can use the jwt.io tool to generate cryptographic keys and sign your JWTs.

Warning: These examples use a shared public key. Ensure you use your own public key in production.

1. Create secrets by replacing the RSA key strings with your own from jwt.io. The credentials are stored in Secrets with a kongCredType key whose value indicates the type of credential.

    kubectl create secret \
      generic admin-jwt  \
      --from-literal=key="admin-issuer" \
      --from-literal=algorithm=RS256 \
      --from-literal=secret="dummy" \
      --from-literal=rsa_public_key="-----BEGIN PUBLIC KEY-----
   MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr6m2/8lMUCiBBgCXFf8B
   DNBZ1Puk2JchjjrKQSiAbkhMgcBUzXqUaxZDc8S3s4/E1Y8HT5JMML1wF6h/AIVM
   FjL1F+qDj0klAHae0tfAU3B2pvUpOSkWU1wWJxQDUH+CF2ihKdEhYMcQv1HGsyZM
   FNuhYbzo9gjcTegQDHgJZd0BSoNxVBvSjE/adUU7kYuAomLDP7ETqlSSWlgIEUxL
   FGhdch0x21J7OETlWJI3UbZxKyCOjWpqcuXYgTRnrHHD8Sy2LWs6hSIToO2ZwWHJ
   HLcyt026eWtIhzu9NHfvU74QGLcAuDooRqtbG/u1pd8NFC7GwLqv6aIoSEvPJhbC
   Br+HeihpCtWg4viM/uWG6La6h0aGpS5VLI/jjDfPN9yN5Yg57lHnipQNMeSisuAE
   a10LKm5l4O6MC1VrFEqZWVGVZ/B+jEFlaqGPDSd3YvIaM7vk7S9TB4O5tEPaJ2XH
   YQv5LtOyGxy0QpI3PyaD1Tks28wDotYcOsPMP59v7LlFewhmMw2eqzJ1lgQ3CuLr
   p343+BMdTfLiw4Nv2h8EVFp3FLpr/xBbeM9ifkloTis+QJsxbnelGF0SzhBP5W4M
   Fz/+NmBYpY72Q+XtoszN4E1QUsk1InJ3Wf6hZm3z/CKZLbKIn/UTYTjzKIBPQdLX
   C6V0e/O3LEuJrP+XrEndtLsCAwEAAQ==
   -----END PUBLIC KEY-----"
    kubectl label secret admin-jwt konghq.com/credential=jwt
   
    kubectl create secret \
      generic user-jwt  \
      --from-literal=key="user-issuer" \
      --from-literal=algorithm=RS256 \
      --from-literal=secret="dummy" \
      --from-literal=rsa_public_key="-----BEGIN PUBLIC KEY-----
   MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr6m2/8lMUCiBBgCXFf8B
   DNBZ1Puk2JchjjrKQSiAbkhMgcBUzXqUaxZDc8S3s4/E1Y8HT5JMML1wF6h/AIVM
   FjL1F+qDj0klAHae0tfAU3B2pvUpOSkWU1wWJxQDUH+CF2ihKdEhYMcQv1HGsyZM
   FNuhYbzo9gjcTegQDHgJZd0BSoNxVBvSjE/adUU7kYuAomLDP7ETqlSSWlgIEUxL
   FGhdch0x21J7OETlWJI3UbZxKyCOjWpqcuXYgTRnrHHD8Sy2LWs6hSIToO2ZwWHJ
   HLcyt026eWtIhzu9NHfvU74QGLcAuDooRqtbG/u1pd8NFC7GwLqv6aIoSEvPJhbC
   Br+HeihpCtWg4viM/uWG6La6h0aGpS5VLI/jjDfPN9yN5Yg57lHnipQNMeSisuAE
   a10LKm5l4O6MC1VrFEqZWVGVZ/B+jEFlaqGPDSd3YvIaM7vk7S9TB4O5tEPaJ2XH
   YQv5LtOyGxy0QpI3PyaD1Tks28wDotYcOsPMP59v7LlFewhmMw2eqzJ1lgQ3CuLr
   p343+BMdTfLiw4Nv2h8EVFp3FLpr/xBbeM9ifkloTis+QJsxbnelGF0SzhBP5W4M
   Fz/+NmBYpY72Q+XtoszN4E1QUsk1InJ3Wf6hZm3z/CKZLbKIn/UTYTjzKIBPQdLX
   C6V0e/O3LEuJrP+XrEndtLsCAwEAAQ==
   -----END PUBLIC KEY-----"
    kubectl label secret user-jwt konghq.com/credential=jwt
   

Validation requirements impose that even if the secret is not used for algorithm RS256 or ES256 the field secret must be present, so put some dummy value for it.

The results should look like this:

  secret/admin-jwt created
  secret/admin-jwt labeled
  secret/user-jwt created
  secret/user-jwt labeled

To associate the JWT Secrets with your consumers, you must add their name to the credentials array in the KongConsumers.

1. Assign the credentials admin-jwt to the admin.

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

   The results should look like this:

    kongconsumer.configuration.konghq.com/admin patched
   

2. Assign the credentials user-jwt to the user.

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

   The results should look like this:

    kongconsumer.configuration.konghq.com/user patched
   

Send authenticated requests

To send an authenticated request, you must create signed JWTs for your users. Here are the pre-populated examples for both the Admin and User JWTs:

• Show Admin JWT
• Show User JWT

The iss field in the payload matches the value you provided in --from-literal=key= when creating the Kubernetes secret.

1. Copy the “Encoded” value and store it in an environment variable for both the ADMIN_JWT and USER_JWT:

    export ADMIN_JWT=eyJhbG...
    export USER_JWT=eyJhbG...
   

2. Send a request with the Authorization header.

    curl -I -H "Authorization: Bearer ${USER_JWT}" $PROXY_IP/lemon
   

   The results should look like this:

    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 947
    Connection: keep-alive
    Server: gunicorn/19.9.0
    Date: Mon, 06 Apr 2020 06:45:45 GMT
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Credentials: true
    X-Kong-Upstream-Latency: 7
    X-Kong-Proxy-Latency: 2
    Via: kong/3.1.1
   

Adding access control

The JWT plugin and other Kong 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 JWT credential can access any JWT-protected URL, even when the JWT 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. Create an ACL plugin that allows only the admin group.

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: admin-acl
    plugin: acl
    config:
      allow: ['admin']
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/admin-acl created
   

2. Create an ACL plugin that allows both the admin and user group.

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: anyone-acl
    plugin: acl
    config:
      allow: ['admin','user']
    " | kubectl apply -f -
   

   The results should look like this:

    kongplugin.configuration.konghq.com/anyone-acl created
   

3. Add the plugins to the routing configuration you created.

   Gateway API

   Ingress

   kubectl annotate httproute lemon konghq.com/plugins=admin-acl
   kubectl annotate httproute lime konghq.com/plugins=anyone-acl

   kubectl annotate ingress lemon konghq.com/plugins=admin-acl
   kubectl annotate ingress lime konghq.com/plugins=anyone-acl

   The results should look like this:

   Gateway API

   Ingress

   httproute.gateway.networking.k8s.io/lemon annotated
   httproute.gateway.networking.k8s.io/lime annotated

   ingress.networking.k8s.io/lemon annotated
   ingress.networking.k8s.io/lime annotated

4. Add consumers to groups through credentials.

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

   The results should look like this:

    secret/admin-acl created
    secret/user-acl created
   

5. Associate the groups to their consumers through credentials.

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

   The results should look like this:

    kongconsumer.configuration.konghq.com/admin patched
    kongconsumer.configuration.konghq.com/user patched
   

Send authorized requests

1. Send a request as the admin consumer to both the URLS.

    curl -sI $PROXY_IP/lemon -H "Authorization: Bearer ${ADMIN_JWT}" | grep HTTP
    curl -sI $PROXY_IP/lime -H "Authorization: Bearer ${ADMIN_JWT}" | grep HTTP
   

   The results should look like this:

    HTTP/1.1 200 OK
    HTTP/1.1 200 OK
   

2. Send a request as theuser consumer.

    curl -sI $PROXY_IP/lemon -H "Authorization: Bearer ${USER_JWT}" | grep HTTP
    curl -sI $PROXY_IP/lime -H "Authorization: Bearer ${USER_JWT}" | grep HTTP
   

   The results should look like this:

    HTTP/1.1 403 Forbidden
    HTTP/1.1 200 OK