moonming/a6-plugin-consumer-restriction

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)

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 | | 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 |