In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Konnect Plus: Pay-as-you-go from startup friendly to enterprise scale. See Pricing →
Kong Logo
search
Docs
Kong Konnect Platform Konnect Platform Konnect Cloud Kong Gateway (Enterprise) Kong Mesh Plugin Hub
Open Source Kong Gateway (OSS) decK Kubernetes Ingress Controller Insomnia Kuma
Contribute to the docs Contribution guidelines
Support Community Kong U Demos & Labs
Get Started
Plugin Hub
header icon

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.

Note: The functionality of this plugin as bundled with versions of Kong prior to 0.14.1 and Kong Enterprise prior to 0.34 differs from what is documented herein. Refer to the CHANGELOG for details.

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, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • setting a target's health status in the load balancer
  • validating configurations against schemas
  • uploading the declarative configuration using the /config endpoint

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

Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Manager

For example, configure this plugin on a service by making the following request:

1
2
3
4
5

$ 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"

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

First, create a KongPlugin resource:

1
2
3
4
5
6
7
8
9
10

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

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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>

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

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

1
2
3
4
5
6
7
8

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.

Configure this plugin on a service:

  1. In Konnect Cloud, select the service on the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Scroll down to Plugins and click New Plugin.
  4. Find and select the ACL plugin.

  5. Enter the following parameters, updating the default or sample values as needed:

    • Config.Hide Groups Header: select checkbox
  6. Click Create.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. Find and select the ACL plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.

  7. Enter the following parameters, updating the default or sample values as needed:

    • Config.Hide Groups Header: select checkbox
  8. Click Create.

Enabling the plugin on a route

Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Manager

For example, configure this plugin on a route with:

1
2
3
4
5

$ 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"

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

First, create a KongPlugin resource:

1
2
3
4
5
6
7
8
9
10

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

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

1
2
3
4
5
6
7
8

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.

Configure this plugin on a route:

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the ACL plugin.

  6. Enter the following parameters, updating the default or sample values as needed:

    • Config.Hide Groups Header: select checkbox
  7. Click Create.

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. Find and select the ACL plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.

  8. Enter the following parameters, updating the default or sample values as needed:

    • Config.Hide Groups Header: select checkbox
  9. Click Create.

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.

Admin API
Kubernetes
Declarative (YAML)
Kong Manager

For example, configure this plugin globally with:

1
2
3
4
5

$ 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"

Create a KongClusterPlugin resource and label it as global:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

For example, configure this plugin using the plugins: entry in the declarative configuration file:

1
2
3
4
5
6
7

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

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the ACL plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, set the plugin scope to Global.

  6. Enter the following parameters, updating the default/sample values as needed:

    • Config.Hide Groups Header: select checkbox
  7. Click Create.

Parameters

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

Form Parameter Description
name

Type: string		 The name of the plugin to use, in this case acl.
service.id

Type: string		 The ID of the Service the plugin targets.
route.id

Type: string		 The ID of the Route the plugin targets.
enabled

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.allow
semi-optional

Type: array of string elements

Arbitrary group names that are allowed to consume the Service or Route. One of config.allow or config.deny must be specified.
config.deny
semi-optional

Type: array of string elements

Arbitrary group names that are not allowed to consume the Service or Route. One of config.allow or config.deny must be specified.
config.hide_groups_header
required

Type: boolean

Default value: false

Flag that if enabled (true), prevents the X-Consumer-Groups header to be sent in the request to the Upstream service.

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

With a database
Without a database

After you have added an authentication plugin to a Service or a Route, and you have created your Consumers, you can now associate a group to a Consumer using the following request:

1
2

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

consumer: The id or username property of the Consumer entity to associate the credentials to.

form parameter default description
group   The arbitrary group name to associate to the consumer.

You can create ACL objects via the acls: entry in the declarative configuration file:

1
2
3

acls:
- consumer: { consumer }
  group: group1
  • consumer: The id or username property of the Consumer entity to associate the credentials to.
  • group: The arbitrary group name to associate to the Consumer.

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

Note: This endpoint was introduced in Kong 0.11.2.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

$ 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:

1
2
3
4
5
6
7
8
9
10
11
12
13

$ 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

Note: This endpoint was introduced in Kong 0.11.2.

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

1
2
3
4
5
6
7

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

image