ACL plugin | Kong Docs

Restrict access to a Service or a Route by adding Consumers to allowed or denied lists using arbitrary ACL groups. 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, 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 POST, PUT, PATCH, or DELETE ACLs do not work in DB-less mode.

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

curl -X POST http://{HOST}: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:

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:

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:

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:

In Konnect Cloud, select the service on the ServiceHub page.
Scroll down to Versions and select the version.
Scroll down to Plugins and click New Plugin.
Find and select the ACL plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Hide Groups Header: select checkbox
Click Create.

Configure this plugin on a service:

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Services and click View for the service row.
Scroll down to plugins and click Add Plugin.
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.
If the option is available, select Scoped.
Add the service name and ID to the Service field if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Hide Groups Header: select checkbox
Click Create.

Enable the plugin on a route

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Manager

For example, configure this plugin on a route with:

$ curl -X POST http://{HOST}: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:

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:

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.

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

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:

In Konnect Cloud, select the service from the ServiceHub page.
Scroll down to Versions and select the version.
Select the route.
Scroll down to Plugins and click Add Plugin.
Find and select the ACL plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Hide Groups Header: select checkbox
Click Create.

Configure this plugin on a route:

In Kong Manager, select the workspace.
From the Dashboard, select Routes in the left navigation.
Click View for the route row.
Scroll down to plugins and click Add Plugin.
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.
If the option is available, select Scoped.
Add the Route ID if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Hide Groups Header: select checkbox
Click Create.

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

$ curl -X POST http://{HOST}: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:

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:

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

Configure this plugin globally:

In Kong Manager, select the workspace.
From the Dashboard, select Plugins in the left navigation.
Click New Plugin.
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.
If the option is available, set the plugin scope to Global.
Enter the following parameters, updating the default/sample values as needed:
- Config.Hide Groups Header: select checkbox
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 required	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 required 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 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 allowed).

Usage

Before you use the ACL plugin, configure your Service or Route with an authentication plugin so that the plugin can identify the client Consumer making the request.

Associate Consumers to an ACL

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:

curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/acls \
    --data "group=group1, tags={'tag1', 'tag2'}"

CONSUMER: The username property of the Consumer entity to associate the credentials to.

form parameter	default	description
`group`		The arbitrary group name to associate with the consumer.
`tags`		Optional descriptor tags for the group.

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

acls:
- consumer: {CONSUMER}
  group: group1
  tags: { tag1 }

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.
tags: Optional descriptor tags for the group.

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.

Return ACLs

Retrieves paginated ACLs.

curl -X GET http://{HOST}: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" }
        }
    ]
}

Retrieve ACLs by Consumer

Retrieves ACLs by Consumer.

curl -X GET http://{HOST}:8001/consumers/{CONSUMER}/acls

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

CONSUMER: The username or id of the Consumer.

Retrieve Consumer by ID

Retrieves a Consumer by ID if the ACL belongs to the specified Consumer.

curl -X GET http://{HOST}:8001/consumers/{CONSUMER}/acls/{ID}

{
    "group": "foo-group",
    "created_at": 1511391159000,
    "id": "724d1be7-c39e-443d-bf36-41db17452c75",
    "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
}

CONSUMER: The username property of the Consumer entity.

ID: The Consumer ID.

Retrieve the Consumer associated with an ACL

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

curl -X GET http://{HOST}: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.

Upsert an ACL group name

Upserts the group name of the ACL.

curl -X PUT 'http://{HOST}:8001/consumers/{CONSUMER}/acls/{ID}'

{
    "group": "foo-group",
    "created_at": 1511391159000,
    "id": "724d1be7-c39e-443d-bf36-41db17452c75",
    "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
}

CONSUMER: The username property of the Consumer entity.

ID: The Consumer ID.

Update an ACL group by ID

Updates an ACL group name by passing a new group name.

curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/acls \
    --data "group=group1"

{
    "group": "group1",
    "created_at": 1511391159000,
    "id": "724d1be7-c39e-443d-bf36-41db17452c75",
    "consumer": { "id": "89a41fef-3b40-4bb0-b5af-33da57a7ffcf" }
}

CONSUMER: The username property of the Consumer entity.

group: The arbitrary group name to associate to the Consumer.

Delete an ACL group

Deletes an ACL group by ID or group.

curl -X DELETE http://{HOST}:8001/consumers/{CONSUMER}/acls 

A successful DELETE request returns a 204 status.

About this Plugin
Made by
Categories	Traffic Control
DB-less compatible?	Partially
Konnect tier
Konnect Cloud	Available
Version Compatibility
Kong Gateway 2.6.x 2.5.x 2.4.x 2.3.x 2.2.x 2.1.x 1.5.x 1.3-x 0.36-x Kong Gateway (OSS) 2.6.x 2.5.x 2.4.x 2.3.x 2.2.x 2.1.x 2.0.x 1.5.x 1.4.x 1.3.x 1.2.x 1.1.x 1.0.x 0.14.x 0.13.x 0.12.x 0.11.x 0.10.x 0.9.x 0.8.x 0.7.x 0.6.x 0.5.x

Configuration Reference

Enable the plugin on a service

Enable the plugin on a route

Enable the plugin globally

Parameters

Usage

Associate Consumers to an ACL

Upstream Headers

Return ACLs

Retrieve ACLs by Consumer

Retrieve Consumer by ID

Retrieve the Consumer associated with an ACL

Upsert an ACL group name

Update an ACL group by ID

Delete an ACL group

See also