Skip to main content

Authentication: consumers and credentials

To tell your API's clients apart, you create a consumer for each one and give it a credential, usually a key-auth credential that holds a key. key-auth is the authentication plugin these pages follow. It reads the key a request carries and finds the credential that holds it. From then on it treats the request as that consumer's. This page explains consumers, credentials and consumer groups, and what each one changes for a request. How G8 handles a request shows where they sit on the way to your backend.

How key-auth ties a request to a consumer through its credential, and what follows from itOne request, one consumer: what key-auth looks up and what follows from itClientthe mobile app,sending its keyRoute orders-apikey-auth reads the key and findsthe credential that holds it;consumer-restriction lets onlythe consumers it names through4its name, inX-Consumer-UsernameBackendlearns who callsfrom that headerCredentialID mobile-app-key-2026,holding one keyCredentialID mobile-app-key-2027,holding a second key12Consumer mobile-appLabels: team = mobilePlugins: limit-count, 600 aminute by consumer_nameConsumer group: optional3the request now belongs to mobile-appConsumer groupplugins that every consumerin the group runs as well
The numbers match the steps below the picture.
  1. A client sends its key, and key-auth on the route finds the credential that holds it. A request with no key, or with a key no credential holds, is answered 401 and goes no further.
  2. The credential belongs to one consumer, mobile-app. A consumer can hold several credentials. A second key, created while the first one is being replaced, signs in as the same consumer.
  3. The request now belongs to mobile-app. consumer-restriction lets it through because its list names mobile-app, and the plugins of the consumer and of its group join the plugins of the route. Here that is the consumer's own limit-count of 600 requests a minute, counted by consumer_name.
  4. Your backend receives the consumer's username in X-Consumer-Username.

Consumer​

A consumer stands for one client of your APIs, a partner or a team for example. You create it under Consumers with New consumer. Its Username is its identity and cannot be changed later. It is the name your backend receives in X-Consumer-Username, the name consumer-restriction lists, and the name a limit per consumer counts under.

A consumer signs in with its credentials, which are created on its Credentials tab. Its other settings decide what happens once it has signed in.

  • Labels: acl on a route reads them to let the consumer through or refuse it. A label team with the value payments opens a route meant for the payments team.
  • Consumer group: one consumer group, whose plugins apply to the consumer as well.
  • Plugins, added in the consumer's Plugins tab. They act on every route the consumer reaches, once the request is authenticated. A limit-count of 600 requests a minute on mobile-app, counted by consumer_name, counts the app's requests on any route that asks for its key. Left at its default counting key, remote_addr, it would count each client address on its own. The consumer's Plugins tab does not offer key-auth or the other plugins that read a credential. A key or a password goes into a credential instead.
  • Where the route carries the same plugin, the consumer's copy runs instead of the route's, and the copy on the consumer's group when the consumer has none. A route limit of 100 requests a minute gives way to a consumer's own 2000. A plugin that rewrites the request, proxy-rewrite for example, is the exception: where the route carries it too, only the route's copy rewrites the request.

Credential​

A credential is what a consumer signs in with: an API key, a username and password, a signing secret. It belongs to one consumer and is created on that consumer's Credentials tab with New credential. Under Authentication you choose one authentication plugin in Plugin, and the fields below it are that plugin's, the Key of key-auth for example. The Credential ID cannot be changed later.

  • Treat a key like a password: long, random, and one for each client, never a word or a name someone could guess.
  • A consumer can hold several credentials, and each one signs in as that consumer on its own. To replace a key, give the consumer a second one, move your clients over, then delete the first.
  • Secrets inside a credential are shown only to roles that can manage credentials.
  • With key-auth, a key that another credential already carries is refused when you save, whoever it belongs to.

Which plugins read a credential​

The plugins whose reference page has a Credential section check a request against the credentials of your consumers. They are the ones the Plugin list of the credential form offers: basic-auth, hmac-auth, jwe-decrypt, jwt-auth, key-auth, ldap-auth and ldap-auth-advanced. Each of those pages shows the credential its plugin reads.

A credential is read only where its plugin acts. Add the same plugin to the route in its Plugins tab, or to an object whose plugins the route runs, its service for example. key-auth is the plugin these pages follow through. Once it has found the credential, the request belongs to that consumer, your backend receives its username in X-Consumer-Username, and the plugins below act on that name.

Not every plugin that checks a credential also tells the gateway which consumer is calling. The plugins below act only once a plugin has named the consumer. To check the plugin you chose, send a request it accepts and look at what your backend receives. When the request belongs to a consumer, the backend gets its username in X-Consumer-Username.

What acts on the consumer​

Each of these needs, on the same route, a plugin that names the consumer, usually key-auth.

  • consumer-restriction lets only the consumers its list names through; another consumer is answered 403.
  • acl lets a consumer through or refuses it by the consumer's own Labels; a refused consumer is answered 403.
  • limit-count with its counting key set to consumer_name counts the requests of each consumer on their own.
  • The plugins of the consumer and of its consumer group, described above and below.

Consumer group​

A consumer group holds plugins that several consumers share. You create it under Consumers, on the Consumer groups tab, and a consumer joins it through its Consumer group setting. Every consumer in the group runs the group's plugins once the request is authenticated. A limit-count of 1000 requests a minute on a group of partners, counted by consumer_name, holds each partner that signs in to its own 1000. Left at its default counting key, remote_addr, the partners that call from one client address would share one count.

A group's own labels change nothing about traffic. acl reads the labels of the consumer, not those of its group.

People who sign in at an identity provider​

Not every sign-in goes through a consumer. openid-connect sends a person's browser to your identity provider, Keycloak for example, or checks the bearer token the provider issued. The people who sign in there are users of the identity provider. You create no consumer and no credential for them in G8, and openid-connect is not in the Plugin list of the credential form. Your backend learns who they are from the headers openid-connect adds, X-Userinfo among them. The plugins under What acts on the consumer need a named consumer.

G8 dev