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 plugin or OpenID Connect plugin.

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 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.

Developers vs Consumers

Developers from the API Portal can also manage API credentials and utilize access control through subscriptions, but they are typically used in different scenarios.

	Developers	Consumers
Credentials	Managed by developers themselves, invisible to providers	Managed by providers
API Access Control	Developers request access, and providers approve subscriptions.	Providers can directly add or remove consumers from the whitelist/blacklist.

Developers and consumers can be used concurrently for different APIs, operating independently. However, for a given published service and its associated API Product, either API7 Gateway authentication plugins or API Product authentication configurations should be used.

For private services, restrict access through consumer management within API7 Gateway. For public services, group them into well-defined API Products and manage developer access through API Product configurations.

Combining both API7 Gateway authentication plugins and API Product authentication configurations for the same published service is strongly not recommended(only for very special cases). This can lead to authentication conflicts, requiring multiple credentials for successful API requests.

Additional Resources

• Key Concepts
  • Developers
• API Security
  • Set up API authentication
• API Consumption
  • Manage Consumer Credentials
  • Apply list-based access control
• Plugin Hub
  • Consumer Restriction
  • Attach Consumer Label
  • Limit Count
  • Authz Keycloak
  • OpenID Connect plugin.