feat: add acl plugin

[AlinsRan]

Summary

Add the acl plugin, which provides label-based access control for API routes.

Motivation

APISIX currently lacks a native mechanism to restrict API access based on consumer labels or external user attributes. Teams often use labels to represent organizational roles (e.g. team: platform, role: admin) or subscription tiers, and need a simple way to enforce access policies without writing custom plugins.

The acl plugin fills this gap by allowing operators to define allow/deny rules directly on labels — no code required.

Description

The acl plugin checks consumer labels (from APISIX Consumers) or external user attributes (from authentication plugins that set ctx.external_user) against configured allow or deny lists.

Evaluation order: when both allow_labels and deny_labels are configured, deny_labels is checked first. A request is rejected if any deny rule matches, or if no allow rule matches.

Authentication requirement: the request must be authenticated (consumer or external user). Unauthenticated requests return 401.

Label value formats

The plugin supports three formats for label values, with automatic detection when no parser is configured:

Format	Example value	Description
table	["cloud","infra"] (Lua array)	Native APISIX consumer labels
json	[cloud,infra] (JSON string)	JWT/OIDC claims encoded as JSON arrays
segmented_text	"cloud,infra"	Delimiter-separated string, requires external_user_label_field_separator

Scenarios

Scenario 1: Consumer label-based allow list (key-auth)

Restrict an API to consumers belonging to the platform team.

Consumer alice  labels: {team: platform}  → allowed
Consumer bob    labels: {team: sales}     → 403

Plugin config:

{
  "acl": {
    "allow_labels": { "team": ["platform"] }
  }
}

Scenario 2: Consumer label-based deny list

Block guest-role consumers while allowing all others.

Consumer carol  labels: {role: guest}  → 403
Consumer dave   labels: {role: admin}  → allowed

Plugin config:

{
  "acl": {
    "deny_labels": { "role": ["guest"] }
  }
}

Scenario 3: External user (JWT/OIDC) with JSON array claim

JWT payload contains "groups": "[\"cloud\",\"infra\"]" (JSON-encoded string). Extract and match against allow list.

JWT claim: { "groups": "[\"cloud\",\"infra\"]" }

Plugin config:

{
  "acl": {
    "allow_labels": { "groups": ["cloud"] },
    "external_user_label_field": "groups",
    "external_user_label_field_parser": "json"
  }
}

Scenario 4: External user with delimiter-separated claim

JWT payload contains "groups": "cloud,infra" (comma-separated text).

JWT claim: { "groups": "cloud,infra" }

Plugin config:

{
  "acl": {
    "allow_labels": { "groups": ["cloud"] },
    "external_user_label_field": "groups",
    "external_user_label_field_parser": "segmented_text",
    "external_user_label_field_separator": ","
  }
}

Scenario 5: Nested field extraction with JSONPath

JWT payload has a nested structure; use a JSONPath expression to extract the value.

JWT payload: { "user": { "roles": ["admin", "editor"] } }

Plugin config:

{
  "acl": {
    "allow_labels": { "roles": ["admin"] },
    "external_user_label_field": "$..roles",
    "external_user_label_field_key": "roles"
  }
}

Plugin Attributes

Name	Type	Required	Default	Description
allow_labels	object	False*		Labels to allow. At least one of allow_labels or deny_labels is required.
deny_labels	object	False*		Labels to deny. Evaluated before allow_labels.
rejected_code	integer	False	403	HTTP status code on rejection.
rejected_msg	string	False		Custom rejection message.
external_user_label_field	string	False	groups	JSONPath or plain field name to extract from ctx.external_user.
external_user_label_field_key	string	False		Label key name for the extracted value. Defaults to external_user_label_field.
external_user_label_field_parser	string	False		segmented_text, json, or table. Auto-detected if not set.
external_user_label_field_separator	string	False		Regex separator for segmented_text parser. Required when parser is segmented_text.

Changes

• apisix/plugins/acl.lua: Plugin implementation (priority 2410)
• t/plugin/acl.t: 55 test cases for consumer label-based ACL
• t/plugin/acl2.t: Test cases for ctx.external_user based ACL
• docs/en/latest/plugins/acl.md: English documentation
• docs/zh/latest/plugins/acl.md: Chinese documentation
• conf/config.yaml.example: Register plugin at priority 2410
• apisix/cli/config.lua: Add to default plugin list

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new acl plugin to enforce label-based access control on routes, supporting both APISIX consumer labels and externally-provided user attributes (ctx.external_user).

Changes:

• Implement apisix/plugins/acl.lua with allow/deny label logic and optional extraction/parsing from ctx.external_user via JSONPath.
• Add extensive test coverage for consumer-label ACL (t/plugin/acl.t) and a smaller suite for route behavior (t/plugin/acl2.t).
• Register and document the plugin across configs and docs (EN/ZH), including default plugin lists.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
t/plugin/acl2.t	Adds basic route-level ACL validation tests (auth + allow list).
t/plugin/acl.t	Adds comprehensive ACL test matrix for consumer labels + external_user parsing/schema cases.
t/admin/plugins.t	Registers acl in plugin listing tests.
docs/zh/latest/plugins/acl.md	Introduces Chinese documentation for acl plugin usage and config.
docs/zh/latest/config.json	Adds plugins/acl to Chinese docs nav/config.
docs/en/latest/plugins/acl.md	Introduces English documentation for acl plugin usage and config.
docs/en/latest/config.json	Adds plugins/acl to English docs nav/config.
conf/config.yaml.example	Registers acl plugin at priority 2410 in example config.
apisix/plugins/acl.lua	New plugin implementation (schema, label matching, external_user extraction).
apisix/cli/config.lua	Adds acl to the default plugin list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.