a7-plugin-consumer-restriction

name: a7-plugin-consumer-restriction description: >- Skill for configuring the API7 Enterprise Edition consumer-restriction plugin via the a7 CLI. Covers restricting access by consumer name, service ID, or route ID using whitelist/blacklist modes and per-consumer HTTP method restrictions. version: "1.0.0" author: API7.ai Contributors license: Apache-2.0 metadata: category: plugin apisix_version: ">=3.0.0" plugin_name: consumer-restriction a7_commands: - a7 route create - a7 route update - a7 consumer create - a7 consumer update - a7 config sync

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

* 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

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