ACL

Restrict access to a Service or a Route by adding Consumers to allowed or denied lists using arbitrary ACL group names. This plugin requires an authentication plugin (such as Basic Authentication, Key Authentication, OAuth 2.0, and OpenID Connect) to have been already enabled on the Service or Route.

Configuration Reference

This plugin is compatible with requests with the following protocols:

• http
• https

This plugin is partially compatible with DB-less mode.

In DB-less mode, Kong Gateway does not have an Admin API. If using this mode, configure the plugin using declarative configuration.

Consumers and ACLs can be created with declarative configuration.

Admin API endpoints that do POST, PUT, PATCH or DELETE on ACLs will not work on DB-less mode.

Enabling the plugin on a Service

$ curl -X POST http://<admin-hostname>:8001/services/<service>/plugins \
    --data "name=acl"  \
    --data "config.allow=group1" \
    --data "config.allow=group2" \
    --data "config.hide_groups_header=true"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <acl-example>
config: 
  allow:
  - group1
  - group2
  hide_groups_header: true
plugin: acl

apiVersion: v1
kind: Service
metadata:
  name: <service>
  labels:
    app: <service>
  annotations:
    konghq.com/plugins: <acl-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: <service>
  selector:
    app: <service>

plugins:
- name: acl
  service: <service>
  config: 
    allow:
    - group1
    - group2
    hide_groups_header: true

<service> is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

$ curl -X POST http://<admin-hostname>:8001/routes/<route>/plugins \
    --data "name=acl"  \
    --data "config.allow=group1" \
    --data "config.allow=group2" \
    --data "config.hide_groups_header=true"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <acl-example>
config: 
  allow:
  - group1
  - group2
  hide_groups_header: true
plugin: acl

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: <route>
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <acl-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

plugins:
- name: acl
  route: <route>
  config: 
    allow:
    - group1
    - group2
    hide_groups_header: true

<route> is the id or name of the Route that this plugin configuration will target.

Enabling the plugin globally

A plugin which is not associated to any Service, Route, or Consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

$ curl -X POST http://<admin-hostname>:8001/plugins/ \
    --data "name=acl"  \
    --data "config.allow=group1" \
    --data "config.allow=group2" \
    --data "config.hide_groups_header=true"

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-acl>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  allow:
  - group1
  - group2
  hide_groups_header: true
plugin: acl

plugins:
- name: acl
  config: 
    allow:
    - group1
    - group2
    hide_groups_header: true

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Note that the allow and deny models are mutually exclusive in their usage, as they provide complimentary approaches. That is, you cannot configure an ACL with both allow and deny configurations. An ACL with an allow provides a positive security model, in which the configured groups are allowed access to the resources, and all others are inherently rejected. By contrast, a deny configuration provides a negative security model, in which certain groups are explicitly denied access to the resource (and all others are inherently allowed).

Usage

Before you use the ACL plugin, you need to have properly configured your Service or Route with an authentication plugin so that the plugin can identify the client Consumer making the request.

Associating Consumers

$ curl -X POST http://kong:8001/consumers/{consumer}/acls \
    --data "group=group1"

acls:
- consumer: { consumer }
  group: group1

You can have more than one group associated to a Consumer.

Upstream Headers

When a consumer has been validated, the plugin appends a X-Consumer-Groups header to the request before proxying it to the Upstream service, so that you can identify the groups associated with the Consumer. The value of the header is a comma-separated list of groups that belong to the Consumer, like admin, pro_user.

This header will not be injected in the request to the Upstream service if the hide_groups_header config flag is set to true.

Paginate through the ACLs

You can retrieve all the ACLs for all Consumers using the following request:

$ curl -X GET http://kong:8001/acls

{
    "total": 3,
    "data": [
        {
            "group": "foo-group",
            "created_at": 1511391159000,
            "id": "724d1be7-c39e-443d-bf36-41db17452c75",
            "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
        },
        {
            "group": "bar-group",
            "created_at": 1511391162000,
            "id": "0905f68e-fee3-4ecb-965c-fcf6912bf29e",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        },
        {
            "group": "baz-group",
            "created_at": 1509814006000,
            "id": "ff883d4b-aee7-45a8-a17b-8c074ba173bd",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        }
    ]
}

You can filter the list by Consumer by using this other path:

$ curl -X GET http://kong:8001/consumers/{username or id}/acls

{
    "total": 1,
    "data": [
        {
            "group": "bar-group",
            "created_at": 1511391162000,
            "id": "0905f68e-fee3-4ecb-965c-fcf6912bf29e",
            "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
        }
    ]
}

username or id: The username or id of the Consumer whose ACLs need to be listed

Retrieve the Consumer associated with an ACL

Retrieve a Consumer associated with an ACL using the following request:

curl -X GET http://kong:8001/acls/{id}/consumer

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

id: The id property of the ACL for which to get the associated Consumer.

See also

• cidr
• configuration