a7-plugin-consumer-restriction

Overview

The consumer-restriction plugin in API7 Enterprise Edition (API7 EE) restricts access to routes or services based on the authenticated consumer's identity. It supports three 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.
• 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, 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)

1. Blacklist: if consumer matches → 403 immediately.
2. Whitelist: if consumer NOT in whitelist → blocked (unless allowed_by_methods permits).
3. 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
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
a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "jack1",
  "plugins": {
    "key-auth": {"key": "jack1-key"}
  }
}
EOF

a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "jack2",
  "plugins": {
    "key-auth": {"key": "jack2-key"}
  }
}
EOF

# Create route with restriction
a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "restricted",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "whitelist": ["jack1"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 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:

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

3. Restrict Named Consumers

Current API7 EE does not expose consumer group management through the Admin API. Use consumer_name allowlists or denylists when configuring consumer restrictions.

a7 consumer create --gateway-group default -f - <<'EOF'
{
  "username": "acme-corp",
  "plugins": {
    "key-auth": {"key": "acme-key"}
  }
}
EOF

# Route restricted to named consumers
a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "enterprise-only",
  "uri": "/premium/*",
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_name",
      "whitelist": ["acme-corp"]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

4. Method-Level Restrictions

Allow jack1 only POST requests:

a7 route create --gateway-group default -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": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

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

Consumer api-user can only access service 1:

a7 consumer create --gateway-group default -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:

a7 consumer create --gateway-group default -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"
gateway_group: default
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:
      type: roundrobin
      nodes:
        - host: admin-backend
          port: 8080
          weight: 1

  - 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:
      type: roundrobin
      nodes:
        - host: api-backend
          port: 8080
          weight: 1

Common Patterns

Tiered Access Control

{
  "plugins": {
    "key-auth": {},
    "consumer-restriction": {
      "type": "consumer_name",
      "whitelist": ["enterprise-user", "pro-user"],
      "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

---

This page is generated from a7-plugin-consumer-restriction/SKILL.md in the api7/a7 repository. Browse all skills on the AI Agent Skills page.