Skip to content
|
search
Plugin Hub
header icon

ACL

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

Example plugin configuration

The following examples provide some typical configurations for enabling the acl plugin on a service.

Make the following request:

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
    --data "name=acl"  \
    --data "config.allow=group1" \
    --data "config.allow=group2" \
    --data "config.hide_groups_header=true"

Replace SERVICE_NAME|SERVICE_ID with 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_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: acl-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

Replace SERVICE_NAME|SERVICE_ID with 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.

Add this section to your declarative configuration file:

plugins:
- name: acl
  service: SERVICE_NAME|SERVICE_ID
  config: 
    allow:
    - group1
    - group2
    hide_groups_header: true

Replace SERVICE_NAME|SERVICE_ID with the id or name of the service that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. In the Plugins section, click Add Plugin.
  2. Find and select the ACL plugin.

  3. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Services section, click View for the service row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the ACL plugin.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already pre-filled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

The following examples provide some typical configurations for enabling the acl plugin on a route.

Make the following request:

curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
  --data "name=acl"  \
    --data "config.allow=group1" \
    --data "config.allow=group2" \
    --data "config.hide_groups_header=true"

Replace ROUTE_NAME|ROUTE_ID with 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.k8s.io/v1
kind: Ingress
metadata:
  name: ROUTE_NAME|ROUTE_ID
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: acl-example
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          service:
            name: echo
            port:
              number: 80

Replace ROUTE_NAME|ROUTE_ID with 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.

Add this section to your declarative configuration file:

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

Replace ROUTE_NAME|ROUTE_ID with the id or name of the route that this plugin configuration will target.

You can configure this plugin through the Konnect UI.

From the servicehub icon Service Hub, select a service version, then set up the plugin:

  1. Select a route.
  2. In the Plugins section, click Add Plugin.
  3. Find and select the ACL plugin.

  4. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Routes from the menu, then click View for the route row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the ACL plugin.
  5. If the option is available, select Scoped.
  6. Add the route ID if it is not already prefilled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

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.

The following examples provide some typical configurations for enabling the acl plugin globally.

Make the following request:

curl -X POST http://localhost: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

Add a plugins entry in the declarative configuration file:

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

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Plugins from the menu, then click New Plugin.
  3. Find and select the ACL plugin.
  4. If the option is available, set the plugin scope to Global.

  5. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

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

Parameters

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

Form Parameter Description
name

required

Type: string

 The name of the plugin, in this case acl.
instance_name

optional

Type: string

An optional custom name to identify an instance of the plugin, for example acl_my-service.

Useful when running the same plugin in multiple contexts, for example, on multiple services.
service.name or service.id

optional

Type: string

The name or ID of the service the plugin targets.

Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.

Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins.
route.name or route.id

optional

Type: string

The name or ID of the route the plugin targets.

Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.

Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins.
enabled

optional

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.

You can’t 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 with an ACL

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" \
    --data "tags[]=tag1" \
    --data "tags[]=tag2"

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

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

Result:

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

Result:

{
    "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 ACL by ID

Retrieves ACL by ID if the ACL belongs to the specified consumer.

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

Result:

{
    "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 id property of the ACL.

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

Result:

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

ID: The id property of the ACL.

Update and insert an ACL group name

Update and insert the group name of the ACL by passing a new group name.

curl -X PUT http://{HOST}:8001/consumers/{CONSUMER}/acls/{ID}
  --data "group=newgroupname"

CONSUMER: The username property of the consumer entity.

ID: The id property of the ACL.

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"

CONSUMER: The username property of the consumer entity.

Remove an ACL group for a consumer

Deletes an ACL group by ID or group name.

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

ID: The id property of the ACL.

Deletes an ACL group by group name.

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

GROUP: The group property of the ACL.

A successful DELETE request returns a 204 status.

See also

Changelog

Kong Gateway 3.0.x

  • Removed the deprecated whitelist and blacklist parameters. They are no longer supported.

Kong Gateway 2.1.x

  • Use allow and deny instead of whitelist and blacklist