Skip to main content

Plugins

Gate's plugins significantly enhance its capabilities beyond acting as a proxy or external authorizer. With plugins, you can handle token translation, implement rate limiting, enforce role-based access control, and more. For a complete list, refer to the Plugins section.

You can configure these plugins using the plugins option.

info

Plugins are executed in the sequence they are listed in the configuration file, both globally and at the URL level.

Each plugin has its own configuration parameters. Providing an unsupported option will cause a startup error.
You can also enable specific plugins or override parameters for individual URLs. For more details, see URL-specific configuration.

Type

The type option identifies each plugin. Possible values are:

  • httpOnly-proxy
  • mirroring
  • ratelimit
  • token-translation-downgrade
  • token-translation-upgrade
  • token-reminting
  • authentication-proxy
  • validate-jwt
  • request-validator
  • validate-oauth2-token
  • request-oauth2-authenticator
  • opa
  • enforce-openapi-security
  • anonymizer

See the Plugins section for configuration and deployment details.

Enabled flag

The enabled flag controls if a plugin is enabled or disabled by default, applying it to all URLs.

ID

The optional id parameter allows you to assign specific IDs to plugins.
Plugin IDs are case-insensitive and must be unique.

Use plugin IDs to apply specific configuration options to individual plugins. For example, you can enable a given plugin only for certain URLs (see URL-specific configuration).

Intercept mode

The intercept option determines if a plugin intercepts requests, responses, or both.
Possible values are:

  • request: only intercepts requests
  • response: only intercepts responses
  • request_response: intercepts both requests and responses

If unspecified, the default value is request.

caution

Not all plugins support all intercept modes. Check individual plugin documentation for details.

GATE_PLUGINS_0_TYPE=<plugin type>
GATE_PLUGINS_0_ENABLED=true
GATE_PLUGINS_0_INTERCEPT=request
GATE_PLUGINS_0_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_PLUGINS_1_TYPE=<plugin type>
GATE_PLUGINS_1_ID=<plugin ID>
GATE_PLUGINS_1_ENABLED=false
GATE_PLUGINS_1_PARAMETERS_<plugin_parameter>=<plugin parameter value>

Plugins are executed according to their index number. In the example above, the plugin specified by GATE_PLUGINS_0_NAME will be executed first, followed by the plugin specified by GATE_PLUGINS_1_NAME.

URL-specific configuration

You can enable or disable a specific plugin for a given URL using the enabled option.
If not specified, the default configuration applies.

To customize plugin settings for a URL, use the parameters option.
These URL-specific settings merge with the global configuration for each plugin.
To unset a global parameter for a URL, set it to an empty value in the URL configuration.

Here's an example configuration:

GATE_PLUGINS_<plugin number>_TYPE=<plugin type>
GATE_PLUGINS_<plugin number>_ID=<plugin ID>
GATE_PLUGINS_<plugin number>_ENABLED=false
GATE_PLUGINS_<plugin number>_PARAMETERS_<plugin_parameter>=<plugin parameter value>

GATE_URLS_0_PATTERN=svc-another-example.com/
GATE_URLS_0_TARGET=https://another-example:8080
GATE_URLS_0_PLUGINS__<PLUGIN ID>__ENABLED=true
GATE_URLS_0_PLUGINS__<PLUGIN ID>__PARAMETERS_<plugin_parameter>=<plugin parameter value>

When configuring Gate with environment variables, refer to a specific plugin using <PLUGIN ID> in uppercase with two underscores as separators.

info

When merging multiple configurations, URL-specific configurations are appended rather than overridden.

Caching

Most Gate plugins perform external HTTP calls, which can add considerable latency to requests.
Often, the same external call is made for every request (e.g., token translations), and caching can significantly improve performance.

Gate can use the RFC RFC 7234-style Cache-Control header to automatically cache responses.

Gate's fine-grained configuration allows you to specify which URLs and plugins can cache responses and to manually override the Cache-Control policy for specific URLs.

You can specify the following caching parameters:

  • pattern (required): a pattern to match the request URL against. Multiple cache configurations can be specified, and the first matching config is used for each request.

    For example, use to match any request or https://api.slashid.com/ for SlashID Identity Management APIs;

  • disabled (default: false): if true, disables caching for matched requests;

  • distinguish by headers (defaults to none): specifies request headers used to distinguish cached requests.

    For example: "Authorization", "Cookies", "SlashID-*";

  • distinguish by cookies (default: none): specifies request cookies used to distinguish cached requests;

  • cache control override (default: none): overrides the response's Cache-Control.

    For example: max-age=600 caches the response for 10 minutes;

  • respect non cacheable methods (defaults to false): if true only GET requests are cached, otherwise also POST, PUT, etc., are cached.

    Note: caching all methods is often useful for Gate plugins but isn't compliant with RFC 7234;

  • disable http caching (default: false): disables caching for a specific plugin.

Here's an example configuration: