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.
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 requestsresponse
: only intercepts responsesrequest_response
: intercepts both requests and responses
If unspecified, the default value is request
.
Not all plugins support all intercept modes. Check individual plugin documentation for details.
- Environment variables
- HCL
- JSON
- TOML
- YAML
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
.
gate = {
plugins = [
{
type = "<plugin type>"
enabled = true
intercept = "request"
parameters = {
<plugin parameter> = <plugin parameter value>
}
},
{
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters = {
<plugin parameter> = <plugin parameter value>
}
}
]
// ...
}
{
"gate": {
"plugins": [
{
"type": "<plugin type>",
"enabled": true,
"intercept: "request",
"parameters": {
"<plugin parameter>": "<plugin parameter value>"
}
},
{
"type": "<plugin type>",
"id": "<plugin ID>",
"enabled": false,
"parameters": {
<plugin parameter>: <plugin parameter value>
}
},
]
// ...
[[gate.plugins]]
type = "<plugin type>"
enabled = true
intercept = "request"
parameters.<plugin parameter> = <plugin parameter value>
[[gate.plugins]]
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters.<plugin parameter> = <plugin parameter value>
gate:
plugins:
- type: <plugin type>
enabled: true
parameters:
<plugin parameter>: <plugin parameter value>
- type: <plugin type>
id: <plugin ID>
enabled: false
intercept: "request"
parameters:
<plugin parameter>: <plugin parameter value>
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:
- Environment variables
- HCL
- JSON
- TOML
- YAML
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.
gate = {
plugins = [
{
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters = {
<plugin parameter> = <plugin parameter value>
}
}
]
urls = [
{
pattern = "svc-another-example.com/"
target = "https://another-example:8080"
plugins = {
"<plugin ID>" = {
enabled = true
parameters = {
<plugin parameter> = "<plugin parameter value>"
}
}
}
}
]
// ...
}
{
"gate": {
"plugins": [
{
"type": "<plugin type>",
"id": "<plugin ID>",
"enabled": false,
"parameters": {
"<plugin parameter>": "<plugin parameter value>"
}
},
"urls": [
{
"pattern": "svc-another-example.com/",
"target": "https://another-example:8080",
"plugins": {
"<plugin ID>": {
"enabled": true,
"parameters": {
"<plugin parameter>": "<plugin parameter value>"
}
}
}
}
],
// ...
[[gate.plugins]]
type = "<plugin type>"
id = "<plugin ID>"
enabled = false
parameters.<plugin parameter> = <plugin parameter value>
[[gate.urls]]
pattern = "svc-another-example.com/"
target = "https://another-example:8080"
plugins.<plugin ID>.enabled = true
plugins.<plugin ID>.parameters.<plugin parameter> = "<plugin parameter value>"
gate:
plugins:
- type: <plugin type>
id: <plugin ID>
enabled: false
parameters:
<plugin parameter>: <plugin parameter value>
urls:
- pattern: svc-another-example.com/
target: https://another-example:8080
plugins:
<plugin ID>:
enabled: true
parameters:
<plugin parameter>: <plugin parameter value>
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 Access APIs;
disabled
(default:false
): iftrue
, 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'sCache-Control
.For example:
max-age=600
caches the response for 10 minutes;respect non cacheable methods
(defaults tofalse
): iftrue
onlyGET
requests are cached, otherwise alsoPOST
,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: