Plugin overview
A Plugin extends the API Gateway: it authenticates requests, adds security, controls traffic, or transforms requests before they reach the backend. Each plugin belongs to one API Gateway and applies to the scope (Scope) you choose.
Supported plugins
| Plugin | Type | Use it to | Guide |
|---|---|---|---|
| JWT Auth | Authentication | Authenticate requests with the JSON Web Tokens of Consumers. | JWT Auth plugin |
| OpenID Connect | Authentication | Authenticate through an external Identity Provider (Keycloak, Auth0, Google, Okta, and so on) with OAuth 2.0 / OIDC. | OpenID Connect plugin |
| Cors | Security | Add CORS headers so web pages on another domain can call the API from the browser. | CORS plugin |
| Rate Limiting | Traffic Control | Limit the number of requests in a time window. | Rate Limiting plugin |
| Proxy Rewrite | Transformation | Rewrite the host, path, method, and headers of requests before they reach the backend. | Proxy Rewrite plugin |
For the steps, see Add a plugin and the page of each plugin.
Scope
When you create a plugin, you choose where it applies in the Scope section:
| Scope | Applies to | Applied to column in the list |
|---|---|---|
| Global | Every Service, Route, and Consumer of the API Gateway. | Global |
| Scoped | Only the Routes / Services you select with + Add Route / + Add Service. | Route, Service, or Route + Service |
One plugin can be attached to many Routes / Services. When you add a plugin from the Route or Service detail screen, you either reuse an existing plugin (Select existing plugin) or create a new one (Create new plugin).
Direct and inherited plugins
The Plugins tab on the Route / Service detail screen has 2 sub-tabs:
| Sub-tab | Meaning |
|---|---|
| Explicit Plugin | Plugins attached directly to the Route / Service you are viewing. You add plugins on this sub-tab. |
| Implicit Plugin | Plugins the Route / Service gets from elsewhere, read-only: Global plugins, or plugins attached to the Service that the Route uses through Via Service. |
Example: a Rate Limiting plugin is attached to the order-service Service. Every Route that uses Via Service to order-service shows this plugin on the Implicit Plugin sub-tab, so you do not attach it to each Route again.
Plugins and other modules
| Module | Relation to plugins |
|---|---|
| Route | Target of the Scope. The Plugins tab has Explicit Plugin / Implicit Plugin, and you can add plugins there. |
| Service | Target of the Scope. Plugins attached to a Service are inherited by Routes that use Via Service. |
| Consumer | Authentication plugins identify requests by the Credentials of Consumers. The Global scope also covers Consumers. |
| Upstream | Plugins are not attached to an Upstream directly. To apply a plugin to requests sent to an Upstream, attach it to the Route or Service that uses that Upstream. |
Common plugin combinations
Some plugins only work together with other components:
| Goal | What you need |
|---|---|
| Authenticate requests with JWT | The JWT Auth plugin on the Route / Service + a Consumer with a JWT credential. |
| Limit requests per customer | The Rate Limiting plugin with limit_by set to consumer + an authentication plugin (JWT Auth, OpenID Connect) on the same Route / Service. |
| A frontend on another domain calls the API with a token | The Cors plugin + JWT Auth, with run_on_preflight of JWT Auth kept at false. |
| Pass the Consumer name to the backend | The Proxy Rewrite plugin with the $consumer_name variable + an authentication plugin that runs first. |