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.
Enable the plugin on a service
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong 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
Kong 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.
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:
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
required
Type: string |
The name of the plugin, 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
required
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 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.
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 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}
{
"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
{
"created_at":1507936639000,
"username":"foo",
"id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}
ID
: The id
property of the ACL.
Upsert an ACL group name
Upserts 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