Configuring Kong Plugins
Introduction
In case you have to change something when proxying a request via the API Gateway, you can do that via Kong Plugins. Some of the functionality which the API Portal provides out of the box are actually - under the hood - leveraging Kong's plugin mechanism. This applies foremost to the authentication mechanisms (via API Key or OAuth2), where the plugins key-auth
, acl
(Access Control Lists) and/or oauth2
are automatically configured to achieve the desired effect (i.e. protecting the backend API against unauthorized calls).
Kong's modus operandi
Mashape Kong knows, very coarsely speaking, three different entities which it works with for configuration:
- APIs
- Consumers
- Plugins
APIs are the entities Kong uses to know which end points to proxy to which backends. This is what you configure when you define APIs for use with the API Portal.
For Kong, Consumers are entities which can be used when applying plugins to API routes. Kong is agnostic to what kind of Consumer may be behind (e.g. "User", "Application",...), this is up to the API Gateway operator to decide. For the wicked API Portal, consumers map to API Subscriptions, i.e. a combination of an API, an Application and an API Plan.
In order to achieve desired effects on the API routes, e.g. rate limiting or access control, Kong makes use of Plugins. Most plugins can either be applied to an API, to a Consumer, or to a combination of both (which then applies the plugin for a specific API for a specific consumer).
In most cases, you will not need to bother very much about the explicit configuration of the plugins, as the API Portal does this for you, but there are some things which are important.
Which Plugins are used out of the box
The following plugins are used by the API Portal "under the hood", and MUST NOT be configured multiple times:
key-auth
acl
oauth2
In order to achieve the functionality of the API Portal and Gateway, the Kong adapter works as follows:
- For each API, configure an Access Control List (the
acl
plugin) and set it to contain only a group called exactly as the API - For each subscription in the API Portal
- Create a consumer named after the API and Application it is for (e.g.
my-app$users-api
) - When using API keys, add the
key-auth
plugin for this consumer, so that passing in the API Key as a header will immediately identify this consumer when calling the backend - When using OAuth 2.0 Client Credentials, add the
oauth2
plugin, so that the token which is issued can be used to identify the Consumer which was created - Add the consumer to the
acl
group of the API for which the subscription is valid
- Create a consumer named after the API and Application it is for (e.g.
- In case the subscription plan has a plugin defined, this plugin is also added to the API, giving the
consumer_id
as a restriction for the plugin; this enables having e.g. different rate limiting settings for different consumers/subscriptions, depending on the API Plan.
This mechanism ensures that each API key can only be used for one subscription to one API (for one application).
Supported Plugins
The API Portal kickstarter has support for selected Kong Plugins, for which there exists a simple way to configure them. These are the following plugins:
- Correlation ID
- Logging (only API level)
- Rate Limiting
- CORS (only API level)
To some extent, also the request-transformer
plugin is supported, which makes it possible to add or delete specific parts of requests, e.g. adding headers.
The plugin configuration can be found for both Plans and API Kong Configurations. This is supported in the kickstarter:
Correlation ID
Use this plugin to insert a correlation ID (Correlation-Id
) header into the proxied request. If such a header is already present, simply pass it on. Otherwise create a new one, based on a UUID.
Logging
To be discussed, I am not happy with this.
Rate Limiting
The rate limiting plugin documentation is partly self documenting in the kickstarter; for more information also see the plugin documentation on Mashape's Kong pages:
CORS
TODO: Currently, there is no way to use registered application's hosts as Origin
in this setting. This is due to a limitation of the Kong Plugin, which is not able to use more than a single origin host currently. This is about to change (see e.g. PR #1774 in Mashape/Kong, and then a varying origin header may be supported here.
Other Plugins
If you need addition Plugin Configuration, you can use the kickstarter's "Other Plugins" functionality. It just lets you edit the JSON configuration of the plugin section of an API or Plan. This means you obviously have to know to write a correct configuration, according to the Kong plugin documentation.
There are currently two special things which kickstarter can help you with: Adding specific headers using the request-transformer
plugin; this is described below.
The Forwarded
Header
Use the "Add Forwarded Header" in order to configure Kong to always send a Forwarded
header, following the RFC 7239 recommendation. This will make the API Gateway always add a header in the following form:
Forwarded: host=api.yourcompany.com;proto=https;prefix=/apiprefix;port=443
Adding Basic Auth to the Backend Service
Using the same plugin, kickstarter can also be used to define a Authorization: Basic ...
header for backend authorization. It works in a similar way as the Forwarded
header, with the following difference: The header value is not directly written into the configuration, but is (as it's a credential), put into an environment variable:
The environment variable can in turn be reviewed in the "Environments" section, where you both can change the value of the variable, or define alternate values for different environments, e.g. if you use different credentials for different environments:
The kickstarter will by default encrypt the credentials, which probably makes sense.
Other Kong Plugins
Other Kong Plugins can be used to achieve other behaviors, such as
- Whitelisting
- Blacklisting
- Rate Limiting over data size
- ...
Future Work
If you need configuration UI for other plugins, please raise an Issue.