a6-plugin-consumer-restriction

Overview

The consumer-restriction plugin restricts access to routes or services based on the authenticated consumer's identity. It supports four restriction types and three matching modes (blacklist, whitelist, method-level).

Priority: 2400 (runs in the access phase after authentication plugins).

Prerequisite: MUST be paired with an authentication plugin (key-auth, basic-auth, jwt-auth, hmac-auth, wolf-rbac, etc.) to identify the consumer.

When to Use

Restrict specific routes to certain consumers or consumer groups
Implement tiered access (free vs premium consumers)
Control which HTTP methods each consumer can use
Restrict consumers to specific services or routes

Plugin Configuration Reference

Field	Type	Required	Default	Description
`type`	string	No	`consumer_name`	Restriction type: `consumer_name`, `consumer_group_id`, `service_id`, `route_id`
`whitelist`	array[string]	One of three*	—	Allowed identifiers
`blacklist`	array[string]	One of three*	—	Blocked identifiers
`allowed_by_methods`	array[object]	One of three*	—	Per-consumer HTTP method restrictions
`allowed_by_methods[].user`	string	No	—	Consumer username
`allowed_by_methods[].methods`	array[string]	No	—	Allowed HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE, PURGE
`rejected_code`	integer	No	`403`	HTTP status code for rejected requests (≥ 200)
`rejected_msg`	string	No	`"The {type} is forbidden."`	Custom rejection message

* At least one of whitelist, blacklist, or allowed_by_methods is required.

Evaluation Priority

blacklist (highest) > whitelist > allowed_by_methods (lowest)

Blacklist: if consumer matches → 403 immediately
Whitelist: if consumer NOT in whitelist → blocked (unless allowed_by_methods permits)
allowed_by_methods: if consumer's method not in allowed list → blocked

Restriction Type Placement

Type	Configure On	Description
`consumer_name`	Route/Service	Restrict which consumers can access this route
`consumer_group_id`	Route/Service	Restrict which consumer groups can access this route
`service_id`	Consumer	Restrict which services this consumer can access
`route_id`	Consumer	Restrict which routes this consumer can access

Step-by-Step Examples

1. Whitelist by Consumer Name

Only allow jack1 to access the route:

# Create consumers with auth
a6 consumer create -f - <<'EOF'
{
  "username": "jack1",
  "plugins": {
    "key-auth": {"key": "jack1-key"}
  }
}
EOF

a6 consumer create -f - <<'EOF'
{
  "username": "jack2",
  "plugins": {
    "key-auth": {"key": "jack2-key"}
  }
}
EOF

# Create route with restriction
a6 route create -f - <<'EOF'
{
  "id": "restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["jack1"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

curl -H 'apikey: jack1-key' /api/data → 200 OK
curl -H 'apikey: jack2-key' /api/data → 403 {"message":"The consumer_name is forbidden."}

2. Blacklist by Consumer Name

Block bad-actor while allowing everyone else:

a6 route create -f - <<'EOF'
{
  "id": "blacklisted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "blacklist": ["bad-actor"],
      "rejected_code": 403,
      "rejected_msg": "Access denied"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

3. Restrict by Consumer Group

Only allow consumers in enterprise group:

# Create consumer group
a6 consumergroup create -f - <<'EOF'
{
  "id": "enterprise",
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 60,
      "group": "enterprise"
    }
  }
}
EOF

# Create consumer in the group
a6 consumer create -f - <<'EOF'
{
  "username": "acme-corp",
  "plugins": {
    "key-auth": {"key": "acme-key"}
  },
  "group_id": "enterprise"
}
EOF

# Route restricted to enterprise group
a6 route create -f - <<'EOF'
{
  "id": "enterprise-only",
  "uri": "/premium/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_group_id",
      "whitelist": ["enterprise"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

4. Method-Level Restrictions

Allow jack1 only POST requests:

a6 route create -f - <<'EOF'
{
  "id": "method-restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "allowed_by_methods": [
        {
          "user": "jack1",
          "methods": ["POST"]
        },
        {
          "user": "admin",
          "methods": ["GET", "POST", "PUT", "DELETE"]
        }
      ]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"backend:8080": 1}
  }
}
EOF

5. Restrict Consumer to Specific Services (Consumer-Level Config)

Consumer api-user can only access service 1:

a6 consumer create -f - <<'EOF'
{
  "username": "api-user",
  "plugins": {
    "key-auth": {"key": "api-user-key"},
    "consumer-restriction": {
      "type": "service_id",
      "whitelist": ["1"],
      "rejected_code": 403
    }
  }
}
EOF

6. Restrict Consumer to Specific Routes (Consumer-Level Config)

Consumer limited-user can only access route 1:

a6 consumer create -f - <<'EOF'
{
  "username": "limited-user",
  "plugins": {
    "key-auth": {"key": "limited-key"},
    "consumer-restriction": {
      "type": "route_id",
      "whitelist": ["1"],
      "rejected_code": 401
    }
  }
}
EOF

Config Sync Example

version: "1"
consumers:
  - username: admin
    plugins:
      key-auth:
        key: admin-key
  - username: readonly
    plugins:
      key-auth:
        key: readonly-key

routes:
  - id: admin-api
    uri: /admin/*
    plugins:
      key-auth: {}
      consumer-restriction:
        whitelist:
          - admin
        rejected_code: 403
        rejected_msg: "Admin access required"
    upstream_id: admin-backend

  - id: public-api
    uri: /api/*
    plugins:
      key-auth: {}
      consumer-restriction:
        allowed_by_methods:
          - user: readonly
            methods: ["GET"]
          - user: admin
            methods: ["GET", "POST", "PUT", "DELETE"]
    upstream_id: api-backend

Common Patterns

Tiered Access Control

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_group_id",
      "whitelist": ["enterprise", "pro"],
      "rejected_code": 402,
      "rejected_msg": "Upgrade required for this endpoint"
    }
  }
}

Hide Endpoint Existence

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["admin"],
      "rejected_code": 404,
      "rejected_msg": "Resource not found"
    }
  }
}

Troubleshooting

Symptom	Cause	Fix
401 "please check the consumer_name"	No auth plugin or consumer not authenticated	Add `key-auth`/`jwt-auth` to the route
403 but consumer should be allowed	Consumer not in whitelist or is in blacklist	Verify consumer username matches whitelist entry exactly
`allowed_by_methods` ignored	Whitelist also set (higher priority)	Remove whitelist or use only one mode
`service_id` restriction not working	Configured on route instead of consumer	Move `consumer-restriction` config to consumer plugins
`route_id` restriction not working	Configured on route instead of consumer	Move `consumer-restriction` config to consumer plugins