<commit_before>---
id: page-plugin
title: Plugins - ACL
header_title: ACL
header_icon: /assets/images/icons/plugins/acl.png
breadcrumbs:
  Plugins: /plugins
nav:
  - label: Usage
    items:
      - label: Associating Consumers
      - label: Upstream Headers
      - label: Paginate through the ACLs
      - label: Retrieve the Consumer associated with an ACL

description: |
  Restrict access to a Service or a Route (or the deprecated API entity) by whitelisting or blacklisting consumers using arbitrary ACL group names. This plugin requires an [authentication plugin](/about/faq/#how-can-i-add-authentication-to-a-microservice-api) to have been already enabled on the Service or the Route (or API).

params:
  name: acl
  api_id: true
  service_id: true
  route_id: true
  consumer_id: false
  config:
    - name: whitelist
      required: semi
      default:
      value_in_examples: group1, group2
      description: |
        Comma separated list of arbitrary group names that are allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.
    - name: blacklist
      required: semi
      default:
      description: |
        Comma separated list of arbitrary group names that are not allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.
  extra: |
    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 Service or Route (or API) with an [authentication plugin][faq-authentication] so that the plugin can identify who is the client [Consumer][consumer-object] making the request.

### Associating Consumers

Once you have added an authentication plugin to a Service or a Route (or API) and you have created your [Consumers][consumer-object], you can now associate a group to a [Consumer][consumer-object] using the following request:

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

`consumer`: The `id` or `username` property of the [Consumer][consumer-object] 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 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`.

### Paginate through the ACLs

<div class="alert alert-warning">
  <strong>Note:</strong> This endpoint was introduced in Kong 0.11.2.
</div>

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

```bash
$ curl -X GET http://kong:8001/acls

{
    "total": 3,<commit_msg>docs(acl) document the 'hide_groups_header' config option<commit_after>---
id: page-plugin
title: Plugins - ACL
header_title: ACL
header_icon: /assets/images/icons/plugins/acl.png
breadcrumbs:
  Plugins: /plugins
nav:
  - label: Usage
    items:
      - label: Associating Consumers
      - label: Upstream Headers
      - label: Paginate through the ACLs
      - label: Retrieve the Consumer associated with an ACL

description: |
  Restrict access to a Service or a Route (or the deprecated API entity) by whitelisting or blacklisting consumers using arbitrary ACL group names. This plugin requires an [authentication plugin](/about/faq/#how-can-i-add-authentication-to-a-microservice-api) to have been already enabled on the Service or the Route (or API).

params:
  name: acl
  api_id: true
  service_id: true
  route_id: true
  consumer_id: false
  config:
    - name: whitelist
      required: semi
      default:
      value_in_examples: group1, group2
      description: |
        Comma separated list of arbitrary group names that are allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.
    - name: blacklist
      required: semi
      default:
      description: |
        Comma separated list of arbitrary group names that are not allowed to consume the Service or the Route (or API). One of `config.whitelist` or `config.blacklist` must be specified.
    - name: hide_groups_header
      required: false
      default: false
      value_in_examples: true
      description: |
        Flag which if enabled (`true`), prevents the `X-Consumer-Groups` header to be sent in the request to the upstream service. 
  extra: |
    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 Service or Route (or API) with an [authentication plugin][faq-authentication] so that the plugin can identify who is the client [Consumer][consumer-object] making the request.

### Associating Consumers

Once you have added an authentication plugin to a Service or a Route (or API) and you have created your [Consumers][consumer-object], you can now associate a group to a [Consumer][consumer-object] using the following request:

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

`consumer`: The `id` or `username` property of the [Consumer][consumer-object] 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 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

<div class="alert alert-warning">
  <strong>Note:</strong> This endpoint was introduced in Kong 0.11.2.
</div>

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

```bash
$ curl -X GET http://kong:8001/acls

{
    "total": 3,
{'fraction_non_alphanumeric': 0.07374242823281538, 'fraction_numerical': 0.004213853041875165, 'mean_word_length': 3.6226415094339623, 'pattern_counts': {'":': 2, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '762398', 'n_tokens_mistral': 2064, 'n_tokens_neox': 1957, 'n_words': 974}