Restrict access to an API by whitelisting or blacklisting consumers using arbitrary ACL group names. This plugin requires an authentication plugin to have been already enabled on the API.


Configuration

Configuring the plugin is straightforward, you can add it on top of an API by executing the following request on your Kong server:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=acl" \
    --data "config.whitelist=group1, group2"

api: The id or name of the API that this plugin configuration will target

You can also apply it for every API using the http://kong:8001/plugins/ endpoint. Read the Plugin Reference for more information.

form parameter default description
name The name of the plugin to use, in this case: acl
config.whitelist
semi-optional
Comma separated list of arbitrary group names that are allowed to consume the API. One of config.whitelist or config.blacklist must be specified.
config.blacklist
semi-optional
Comma separated list of arbitrary group names that are not allowed to consume the API. One of config.whitelist or config.blacklist must be specified.

Note that the whitelist and blacklist models are mutually exclusive in their usage, as they provide complimentary approaches. That is, you cannot configure an ACL with both whitelist and blacklist configurations. An ACL with a whitelist 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 blacklist configuration provides a negative security model, in which certain groups are explicitly denied access to the resource (and all others are inherently allowed).


Usage

In order to use this plugin, you need to properly have configured your APIs with an authentication plugin so that the plugin can identify who is the client Consumer making the request.

Associating Consumers

Once you have added an authentication plugin to an API, and you have created your Consumers, you can now associate a group to a Consumer using the following request:

$ 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 have more than one group associated to a consumer.

Upstream Headers

When a consumer has been validated, the plugin will append a X-Consumer-Groups header to the request before proxying it to the upstream API/Microservice, 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.

Keep up with the latest features