Skip to main content

Allow only named clients

key-auth lets every consumer with a known key through. consumer-restriction narrows that to the consumers you name. This guide lets only mobile-app call orders-api, then widens it to a team whose members change, through a consumer group. At the end, a consumer the list does not name is answered 403 even with a valid key.

Before you start​

  • This guide starts from orders-api as Route requests to a backend leaves it, with key-auth from Require an API key. A plugin from another guide that this page does not name can change the answers below; remove it first or work on a copy of the route.
  • consumer-restriction and acl from Allow a team by label stack on a route, and a request must pass both. If you put acl on orders-api, remove it first, or every consumer is refused by one of the two.
  • The consumers mobile-app and partner-portal, each with a key, from Require an API key.
  • If you put partner-portal in the group partners in Give a group of clients one limit, the answers of the group section below change for it. It is then a consumer in another group, answered 403 and not 401.
  • The host name of your gateway. In the console it is the first part of the Address line on a route's Overview tab, api.example.com in this page's examples; replace it in every request below.
  • The requests below call /orders/2001.
  • On a route that already serves clients, list every consumer that must keep calling it before you add the plugin.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Add consumer-restriction to the route​

Open orders-api under Routes, select its Plugins tab, then Add plugin at the top right of the tab. Open the Security category, or type consumer-restriction in the search box. Select consumer-restriction, then Configure.

2. Name who may pass​

Leave Type at consumer_name, so the list holds consumers' usernames. In Whitelist, type a value and press Enter for each, here mobile-app. Leave the other fields as they are. Select Add plugin at the bottom of the panel. The plugin is saved like this:

consumer-restriction · as the console saves it
{
  "type": "consumer_name",
  "whitelist": [
    "mobile-app"
  ]
}

From now on, every other consumer is answered 403, even with a valid key, before the request reaches your backend.

Check it​

Send a request with the key of mobile-app, then with the key of partner-portal, then with no key.

curl
curl -i -L 'https://<gateway host>/orders/2001' \
  -H 'x-api-key: <the key of mobile-app>'
With the key of mobile-app
A request with the key of mobile-app passes and reaches your backend, which receives X-Consumer-Username: mobile-app.
With the key of partner-portal
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.
Without a key
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 without key-auth
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.

Let a team in instead​

A list of names has to change every time the team does. For a team, gather its consumers in a consumer group and let the group through.

1. Create the group​

Under Consumers, open the Consumer groups tab and select New consumer group. Set ID to mobile-team and Name to Mobile team. The ID is what the plugin compares, and it cannot be changed later. Select Create consumer group.

The General section of the new-consumer-group form, with the ID mobile-team and the name Mobile team filled in.

2. Put the team's consumers in the group​

Open mobile-app under Consumers and select Edit consumer. Under General, pick mobile-team in Consumer group and select Save consumer. Do the same for every consumer of the team. A consumer you create later can join from the start, in the same field of New consumer.

The Edit consumer form of mobile-app, with the consumer group mobile-team picked.

3. Switch the plugin to the group​

Back on the route's Plugins tab, select consumer-restriction in the list of plugins, then Edit. Set Type to consumer_group_id. In Whitelist, remove mobile-app and type mobile-team, the group's ID. Select Save plugin. The plugin is now saved like this:

consumer-restriction · as the console saves it
{
  "type": "consumer_group_id",
  "whitelist": [
    "mobile-team"
  ]
}

Send the same requests again, with the key of mobile-app and then with the key of partner-portal.

A consumer in the group
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 no group
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.
A group with the same name under another ID
The list holds group IDs, not names: a consumer whose group carries the name mobile-team under another ID is answered 403.

What to know​

  • The plugin reads the consumer that key-auth named. A request without a valid key is answered 401 by key-auth before consumer-restriction reads anything. On a route without a plugin that names the consumer, every request is answered 401, valid key or not.
  • With Type at consumer_group_id, a consumer in no group at all is answered 401, and a consumer in a group the list does not name 403. The list holds group IDs, never group names.
  • Rejected message replaces the text in the body of a refused request, so your clients read your words.
G8 dev