Skip to main content

Allow a team by label

A label is a pair you name yourself and put on a consumer, team with the value payments for example. acl on a route reads it and lets the consumer through or refuses it. The route lists the label, not the consumers, so a consumer labelled later is covered without touching the route. This guide opens orders-api to the payments team only. At the end, a consumer whose team label lists payments reaches your backend, and every other consumer 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.
  • acl and consumer-restriction from Allow only named clients stack on a route, and a request must pass both. If you put consumer-restriction on orders-api, remove it first, or every consumer is refused by one of the two.
  • The consumer mobile-app with its key, and two more consumers, payments-app and ops-console. Create each as step 4 of Require an API key shows, and give it a key as Give a client its key, and replace it shows, with the credential IDs payments-app-key-2026 and ops-console-key-2026.
  • A label name you choose for what you allow by, team here, and the values each consumer gets. Nothing about team is built in; acl compares the name on the consumer with the same name in its lists.
  • 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/42.
  • The Editor or Environment administrator role in this environment.

Steps​

1. Label each consumer​

Open payments-app under Consumers and select Edit consumer. Under Labels, select the add button below the field. A row opens with the key on the left and the value on the right. Type team and payments, then select Save consumer.

The Labels field of the Edit consumer form, with the key team and the value payments filled in.

Give mobile-app the key team with the value mobile the same way. A value is one word without spaces. A consumer on several teams carries them in one value separated by commas, so give ops-console the key team with the value ops,payments.

2. Add acl 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 acl in the search box. Select acl, then Configure.

3. List the team that may pass​

Allow labels is a box that takes JSON. Type this into it, the label name with the list of values that may pass:

{"team": ["payments"]}

Leave the Behavior section as it is; its external-user fields are not read for consumers. Select Add plugin at the bottom of the panel. The plugin is saved like this:

acl · as the console saves it
{
  "allow_labels": {
    "team": [
      "payments"
    ]
  }
}

From now on, a consumer whose team label does not list payments is answered 403, and a request without a key 401.

Check it​

Send a request with the key of payments-app, then with the key of ops-console, then with the key of mobile-app, then with no key.

curl
curl -i -L 'https://<gateway host>/orders/42' \
  -H 'x-api-key: <the key of payments-app>'
With the key of payments-app or ops-console
A consumer whose team label is payments, such as payments-app, is answered 200 by the backend; so is one whose label lists payments among other teams, such as ops,payments.
With the key of mobile-app
A consumer with another team, such as mobile-app with the team mobile, or with no team label at all, is answered 403 with {"message":"The consumer is forbidden."}.
Without a key
A request without a key is answered 401 with {"message":"Missing API key in request"} by key-auth, before the lists are read.
A label on the consumer group only
A label on the consumer's group is not read: a consumer with no team label of its own is answered 403 even when its consumer group is labelled team payments.

What to know​

  • acl reads the labels of the consumer itself. A label on the consumer's group is not read, so a consumer with no label of its own is refused by an allow list.
  • A consumer that carries none of the listed values is refused, one with no labels at all included.
  • A Deny labels list alone refuses only what it names; a consumer with no labels passes it. With Rejected message set, the refused client reads your words in the body.
  • Without a plugin that names the consumer on the same route, acl has no consumer to read and refuses every request with 401.
G8 dev