consumer-restriction

Allows or denies requests by consumer, group, route or service.

Category SecurityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin consumer-restrictionPriority 2400

What it does

consumer-restriction lets a request through or refuses it by who is calling. It reads the consumer that a plugin on the same route, usually key-auth, has named, by its username or by the ID of its consumer group. Whitelist lists who may pass, Blacklist who may not.

A refused consumer is answered 403 with {"message":"The consumer_name is forbidden."}, or with your Rejected message, even though its key is valid. Without a plugin on the route that names the consumer, every request is answered 401.

When to use it

• Only some clients may call a route, the mobile app for example, while every other consumer is refused even with a valid key.
• A team whose consumers change: gather them in a consumer group and let the group through, so a consumer that joins it later needs no change on the route.
• Keeping one named consumer away from a route every other consumer may use, under Blacklist.
• Limiting a consumer to some methods, reads only for example, under Allowed by methods.

Not for allowing or refusing consumers by a label they carry, their team for example — see acl (Allows or denies consumers by the labels they carry) or allowing or refusing clients by their address — see ip-restriction (Allows or denies clients by IP address or CIDR range).

Guides

Pages that walk through a job with consumer-restriction, step by step.

• Allow only named clientsLet only the consumers you list call a route, by name or by consumer group.

Set it up

Let only the mobile app's consumer call the route

Needs a plugin on the same route that names the consumer, such as key-auth.

Leave Type at consumer_name and fill Whitelist as in the JSON below.

The console's Add plugin panel, filled with this example.

consumer-restriction · as the console saves it

{
  "type": "consumer_name",
  "whitelist": [
    "mobile-app"
  ]
}

What you will see

• A request with the key of mobile-app passes and reaches your backend, which receives X-Consumer-Username: mobile-app.
• A request with the key of partner-portal, a consumer the list does not name, is answered 403 with {"message":"The consumer_name is forbidden."}, though its key is valid.
• A request without a key is answered 401 with {"message":"Missing API key in request"} by key-auth, before consumer-restriction reads anything.
• On a route with no plugin that names the consumer, every request is answered 401 with {"message":"The request is rejected, please check the consumer_name for this request"}, one with the key of mobile-app included.

More scenarios

Let several consumers through and answer the others with your own message

Needs a plugin on the same route that names the consumer, such as key-auth.

Leave Type at consumer_name, fill Whitelist as in the JSON below and set Rejected message to This API key is not allowed on this route..

consumer-restriction · as the console saves it

{
  "type": "consumer_name",
  "whitelist": [
    "mobile-app",
    "partner-portal"
  ],
  "rejected_msg": "This API key is not allowed on this route."
}

What you will see

• Each consumer the list names passes with its own key: requests with the keys of mobile-app and partner-portal are answered 200.
• Any other consumer, here payments-app, is answered 403 with {"message":"This API key is not allowed on this route."}, the message this example sets.

Let only the consumers of one consumer group call the route

Needs a plugin on the same route that names the consumer, such as key-auth; the list holds the group's ID, mobile-team.

Set Type to consumer_group_id and fill Whitelist as in the JSON below.

consumer-restriction · as the console saves it

{
  "type": "consumer_group_id",
  "whitelist": [
    "mobile-team"
  ]
}

What you will see

• A consumer in the group, here mobile-app, passes with its key and reaches your backend, which receives X-Consumer-Username: mobile-app.
• A consumer in another group, here payments-app, is answered 403 with {"message":"The consumer_group_id is forbidden."}.
• A consumer in no group at all, here partner-portal, is answered 401 with {"message":"The request is rejected, please check the consumer_group_id for this request"}, though its key is valid.
• The list holds group IDs, not names: a consumer whose group carries the name mobile-team under another ID is answered 403.

Things to know

• Type — With no plugin on the route that names a consumer, such as key-auth, there is no consumer name, and every request is refused with 401. The value Type names has to be on the request.
• Type — With consumer_group_id, a consumer in no group at all is answered 401, not 403, with {"message":"The request is rejected, please check the consumer_group_id for this request"}.
• Whitelist — With Type consumer_group_id the list holds group IDs, and a group's name is not read: a consumer whose group is named mobile-team under another ID is refused.
• Whitelist — The three lists can be used together. The deny list is read first, and a name on the allow list skips the method limits.
• Rejected message — Sent as the message of the JSON body in place of The consumer_name is forbidden., with the Rejected code.
• Rejected code — Sent exactly as written: 499 closes the connection without an answer, and 200 makes a refusal look like a success.
• AdviceAllow by name for one or two clients. For a team whose members change, allow its consumer group instead, so the route stays as it is when a consumer joins or leaves.

Settings

The fields as the console shows them, section by section.

Typetypestringdefault consumer_name

one of consumer_group_id, consumer_name, route_id, service_id

Whitelistwhitelistarray of stringsRequired unless Blacklist or Allowed by methods is set

Names let through, as Type reads them (consumer names by default), such as alice. Every other name is refused.

at least 1 item

Blacklistblacklistarray of stringsRequired unless Whitelist or Allowed by methods is set

Names refused, as Type reads them (consumer names by default), such as mallory.

at least 1 item

Allowed by methodsallowed_by_methodsarray of objectsRequired unless Blacklist or Whitelist is set

Limit a name to some methods: a row names it and lists the methods it may use. Names without a row are not limited.

at least 1 item

Each item:

Methodsallowed_by_methods[].methodsarray of stringsRequired

at least 1 item · one of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PURGE, PUT, TRACE

Userallowed_by_methods[].userstring

The name this row limits, as Type reads it. A name no row lists is not limited.

Rejected coderejected_codeintegerdefault 403

The status sent on a refusal, such as 403.

200 to 999

Rejected messagerejected_msgstring

at least 1 character

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.