acl

Allows or denies consumers by the labels they carry.

Category SecurityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin aclPriority 2410

What it does

acl lets a request through or refuses it by the labels of the consumer that an authentication plugin on the route, usually key-auth, has named. Allow labels lists the label values that may pass, Deny labels the ones that may not. The labels are set on each consumer under Labels, and acl needs that authentication plugin on the same route.

A refused consumer is answered with the Rejected code, 403 unless you set another, and a JSON body whose message is The consumer is forbidden. or your Rejected message.

When to use it

• A route only one team or tier may call, where membership is a label on the consumer rather than a list of names on every route.
• Keeping one group of consumers, contractors or a trial tier for example, away from a route every other consumer may use.
• Several routes under the same team rule: each reads the labels, so a consumer labelled later is covered without touching the routes.

Not for allowing or refusing consumers by their names or their consumer group, or limiting a consumer to some methods — see consumer-restriction (Allows or denies requests by consumer, group, route or service), allowing or refusing clients by their address — see ip-restriction (Allows or denies clients by IP address or CIDR range) or a decision that reads the path and the method as well as who is calling — see authz-casbin (Authorizes requests with a Casbin model and policy).

Guides

Pages that walk through a job with acl, step by step.

• Allow a team by labelLet consumers through by a label they carry, so a route stays as it is when the team changes.

Set it up

Open the route to the payments team only

Needs an authentication plugin on the same route, such as key-auth, which names the consumer whose labels are read.

Under Basics fill Allow labels as in the JSON below.

The console's Add plugin panel, filled with this example.

acl · as the console saves it

{
  "allow_labels": {
    "team": [
      "payments"
    ]
  }
}

What you will see

• A consumer whose team label is payments, such as payments-app, is answered 200 by the backend; so is one whose label lists payments among other teams, such as ops,payments.
• A consumer with another team, such as mobile-app with the team mobile, or with no team label at all, is answered 403 with {"message":"The consumer is forbidden."}.
• A request without a key is answered 401 with {"message":"Missing API key in request"} by key-auth, before the lists are read.
• A label on the consumer's group is not read: a consumer with no team label of its own is answered 403 even when its consumer group is labelled team payments.

More scenarios

Keep contractors out and tell them why

Needs an authentication plugin on the same route, such as key-auth, which names the consumer whose labels are read; a deny list alone refuses only what it names.

Under Basics fill Deny labels as in the JSON below. Under Behavior set Rejected message to This route is not open to contractors..

acl · as the console saves it

{
  "deny_labels": {
    "team": [
      "contractors"
    ]
  },
  "rejected_msg": "This route is not open to contractors."
}

What you will see

• A consumer whose team label is contractors is answered 403 with {"message":"This route is not open to contractors."}.
• Every other consumer, one with no team label included, is answered 200 by the backend.

Allow callers whose SAML assertion lists the payments team

Needs saml-auth on the same route, which signs the caller in at the identity provider and hands the assertion's attributes on under attrs. The field names the attribute the identity provider sends the team names in, and its values are read as they are, without a parser.

Under Basics fill Allow labels as in the JSON below. Under Behavior set External user label field to $.attrs.groups, set External user label field key to team and leave Rejected code at 403.

acl · as the console saves it

{
  "allow_labels": {
    "team": [
      "payments"
    ]
  },
  "external_user_label_field": "$.attrs.groups",
  "external_user_label_field_key": "team",
  "rejected_code": 403
}

Allow callers whose roles attribute lists the payments team as comma-separated text

Needs saml-auth on the same route, which signs the caller in at the identity provider and hands the assertion's attributes on under attrs. The field names an attribute whose one value is a comma-separated text, payments,ops for example, which the parser splits.

Under Basics fill Allow labels as in the JSON below. Under Behavior set External user label field to $.attrs.roles, set External user label field key to team, set External user label field parser to segmented_text, set External user label field separator to , and leave Rejected code at 403.

acl · as the console saves it

{
  "allow_labels": {
    "team": [
      "payments"
    ]
  },
  "external_user_label_field": "$.attrs.roles",
  "external_user_label_field_key": "team",
  "external_user_label_field_parser": "segmented_text",
  "external_user_label_field_separator": ",",
  "rejected_code": 403
}

Things to know

• Allow labels — Needs an authentication plugin on the route to name the caller: with no consumer and no external user, every request is refused with 401.
• The labels are read from the consumer itself: a team label on its consumer group is not read, so a consumer that carries no label of its own is refused by an allow list.
• A consumer on several teams carries them in one label as comma-separated text, ops,payments. It passes an allow list when any one of them is listed.
• Allow labels — A consumer that carries no label value named in the list is refused, one with no labels at all included.
• Deny labels — A deny list alone refuses only what it names; a consumer with no labels passes it.
• Deny labels — Both lists can be set together, and the deny list is read first. With neither list the save is refused.
• Rejected message — Sent as the message of the JSON body in place of The consumer is forbidden., with the Rejected code.
• Rejected code — Sent exactly as written: 499 closes the connection without an answer, and 200 makes a refusal look like a success.
• External user label field — Read only for a caller that is an external user, never for a consumer. A consumer that signed in with a key, a token or a password is read by its own labels, and the parser fields are not used for it. Leave these fields as they are when your callers are consumers.

Settings

The fields as the console shows them, section by section. A field under “When … is …” is there only while that value is set.

Basics

Allow labelsallow_labelsobjectRequired unless Deny labels is set

Consumer labels to allow, as a label name with a list of values such as {"team": ["payments"]}, where a caller matching none is refused. An object whose keys are any name, each with an array of strings as its value.

at least 1 key · example {"team":["payments"],"tier":["gold"]}

Deny labelsdeny_labelsobjectRequired unless Allow labels is set

Consumer labels to refuse, in the same shape as Allow labels, where a caller matching any of them is refused. An object whose keys are any name, each with an array of strings as its value.

at least 1 key · example {"team":["contractors"]}

Behavior

External user label fieldexternal_user_label_fieldstringdefault groups

A JSONPath into the claims of an external user another plugin identified, such as groups. A path that cannot be parsed is refused at the write.

at least 1 character

External user label field keyexternal_user_label_field_keystring

The label name the values found above are filed under, where empty uses the path itself.

at least 1 character

External user label field parserexternal_user_label_field_parserstring

How an external user's label value is split into labels: a JSON array, a table, or text cut by the separator below. It is never read for a consumer, whose comma-separated label values are split on commas anyway.

one of json, segmented_text, table

When External user label field parser is segmented_text

External user label field separatorexternal_user_label_field_separatorstringRequired

The pattern that splits the external label field into separate labels.

at least 1 character

Rejected coderejected_codeintegerdefault 403

200 to 999

Rejected messagerejected_msgstring

at least 1 character

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.