Consumers

In this document, you will learn the basic concepts of consumers in API7 Enterprise and why you need them. You will be introduced to a few relevant concepts, including how to pass consumer information to upstream, consumer access restriction, as well as consumer authentication and authorization.

Overview

A consumer represents a user, application, or host that sends requests to the API gateway and consumes backend services. It is used together with the authentication system. Each consumer must be configured with at least one authentication credential or integrated with an external authentication system using plugins like authz-keycloak or openid-connect.

The following diagram illustrates an example of API7 Gateway with one route and two consumers. One consumer, FetchBot, is a data fetching bot, and the other consumer, JohnDoe, is a user. The route and consumers are enabled with the key-auth plugin. Therefore, requests will be authenticated with API keys. To access the internal service, FetchBot sends its requests with bot-key and JohnDoe sends his request with john-key.

This configuration ensures that only authenticated requests can interact with the internal service exposed on /petstore.

• If a request is sent to API7 Gateway without any key or with the wrong key, the request is rejected.
• If a request is sent to API7 Gateway with bot-key, the request is authenticated and sent by FetchBot to fetch data from the internal service. The limit-count rate limiting plugin on the FetchBot consumer takes effect, limiting the number of requests within a 5-second window to 2. If the rate-limiting threshold has not been met, the request is forwarded to the upstream service. Otherwise, it is rejected.
• If a request is sent to API7 Gateway with john-key, the request is authenticated and sent by JohnDoe, subsequently being forwarded to the upstream endpoint.

In this scenario, the authentication plugin is executed before the limit-count rate limiting plugin in accordance with the plugins execution phases.

Passing Consumer Information to Upstream

For certain use cases, such as logging, analytics, and auditing, you might want to pass consumer information to upstream services. Consumer information, by default, is not exposed to upstream; however, you can use attach-consumer-label plugin to include the needed information in the header.

Consumer Access Restriction

You can control request access to your API by imposing restrictions based on consumer name, HTTP methods, or other parameters in the consumer-restriction plugin.

For example, if you want to blacklist FetchBot from accessing your internal service without changing any consumers configuration, please refer to Apply List-Based Access Control.

Authentication & Authorization

There are two main design patterns for building authentication and authorization in an API7 Gateway-based architecture.

The first and most commonly adopted approach is to authenticate and authorize requests through a third-party identity provider (IdP), such as Keycloak:

In some environments, a request might need to go through more than one IdP before it can be forwarded to the upstream endpoints. In such cases, you can configure multiple authentication plugins, each corresponding to an IdP on one consumer. API7 Gateway will not show a successful response until all IdPs have granted access to the request.

The second and more basic approach is to perform authentication and authorization on the API7 Gateway itself, using built-in credentials. So far credentials contains Key Authentication, Basic Authentication, JWT Authentication, and HMAC Authentication.

Similar to traditional user logins, each consumer can create multiple credentials, all linked to a single consumer identity. Credentials should be securely stored and regularly updated.

note

Consumer credentials offer enhanced flexibility by allowing multiple credentials per consumer. They replace traditional authentication plugins like key-auth, basic-auth, JWT-auth, and HMAC-auth, providing a more user-friendly experience.

Additional Resource(s)

• API Security
  • Set up API authentication
• API Consumption
  • Manage Consumer Credentials.
  • Apply list-based access control
• Plugin Hub
  • Consumer Restriction