Plugins¶
Plugins add behaviour to requests and responses as they pass through the Obsidian gateway. They can authenticate callers, restrict traffic, transform messages, invoke functions, record logs, and publish operational metrics without requiring the upstream application to implement every capability itself.
The portal currently offers 38 plugin types in eight categories. Thirty-six correspond to standard Kong Gateway plugins. Service Limit and Global Limit are custom Obsidian plugins.
Before adding a plugin¶
Identify:
- the problem the plugin must solve;
- the correct scope—global, service, route, or consumer;
- the credentials, destinations, limits, or headers it requires;
- how the change will be tested; and
- how to restore the previous behaviour if clients are affected.
Plugins run as part of live request processing. Authentication, transformation, termination, and traffic-control changes can affect clients immediately after being enabled.
Understand plugin scope¶
| Scope | Where to add it | Effect |
|---|---|---|
| Global | Gateway Configuration > Plugins > Add Plugins | Applies to every compatible request handled by the gateway. Use only when the behaviour is genuinely required everywhere. |
| Service | Open a service and use its Plugins tab. | Applies to requests for that service. This is normally safer than global scope. |
| Route | Open a route and use its Plugins tab. | Applies only when the request matches that route. |
| Consumer | Open the consumer and add the plugin there. | Applies to requests associated with that consumer where the plugin supports consumer scope. |
If configurations overlap, Kong evaluates the applicable combination and plugin precedence. Do not create several overlapping configurations unless the intended result has been tested.
Plugins list¶
The list shows Name, plugin ID, Scope, what it is Applied To, and the Created date. Use search and filters to find global, scoped, enabled, or disabled plugins. The ON/OFF switch changes whether the saved configuration is active; edit and delete actions depend on your permissions.
Add a global plugin¶
- Open Gateway Configuration > Plugins.
- Select Add Plugins.
- Read the global-scope notice. If only one service, route, or consumer needs the behaviour, return to that resource and add the plugin there instead.
- Select a category and plugin.
- Complete the plugin-specific configuration.
- Review secrets, addresses, limits, and enabled state.
- Save the plugin and test an affected request.
Authentication plugins¶
Authentication plugins establish who is calling an API. Most require matching credentials on a Consumer. Authentication proves identity; use ACL or another authorisation control when only selected authenticated consumers should have access.
| Plugin | What it does | Use it when |
|---|---|---|
Basic Auth (basic-auth) |
Checks a consumer username and password supplied through HTTP authentication headers. | A simple username/password integration is required. Use HTTPS because Base64 encoding is not encryption. |
Key Auth (key-auth) |
Validates an API key supplied in the configured header, query string, or request body location. | Applications need straightforward machine-to-machine API-key authentication. |
OAuth 2.0 (oauth2) |
Adds OAuth 2.0 token issuing and validation using supported grant flows. | Clients require scoped access tokens. The underlying service must be exposed over HTTPS and some flows require an application-owned authorisation page. |
HMAC Auth (hmac-auth) |
Verifies a cryptographic signature created from the request and a shared consumer secret. | Requests must be authenticated and protected against tampering without sending the secret itself. Client clock and signing rules must agree with the gateway. |
JWT (jwt) |
Verifies JSON Web Token signatures and registered claims using consumer credentials. | Clients already use signed JWT bearer tokens. Configure accepted algorithms and claims carefully. |
LDAP Authentication (ldap-auth) |
Validates a username and password by binding to an LDAP directory. | Authentication must use an existing LDAP directory. Confirm encryption, directory host, base DN, and cache behaviour. |
Session (session) |
Creates and validates encrypted browser-session cookies for supported Kong authentication plugins. | A browser client should reuse a secure session instead of supplying primary credentials on every request. Configure cookie security and storage keys carefully. |
Security plugins¶
| Plugin | What it does | Use it when |
|---|---|---|
ACL (acl) |
Allows or denies authenticated consumers according to consumer-group membership. | Authentication is in place, but only selected consumer groups may call the service or route. |
CORS (cors) |
Adds Cross-Origin Resource Sharing headers and handles browser preflight requests. | A browser application hosted on another origin must call the API. Allow only required origins, methods, and headers. |
IP Restriction (ip-restriction) |
Allows or denies requests according to source IP addresses or CIDR ranges. | Access must be restricted by network location. Confirm how proxies and load balancers supply the client IP. |
Bot Detection (bot-detection) |
Blocks known or configured user-agent signatures associated with bots and automated clients. | Basic user-agent-based bot filtering is needed. It is not a complete bot-management or WAF solution. |
ACME (acme) |
Automates certificate issuance and renewal through the ACME protocol, including Let's Encrypt. | Kong-managed TLS certificates should be obtained and renewed automatically. DNS, storage, domains, and challenge routing must be prepared first. |
Traffic Control plugins¶
| Plugin | What it does | Use it when |
|---|---|---|
Rate Limiting (rate-limiting) |
Limits the number of HTTP requests a client can make during configured second-to-year windows. | Services need protection from bursts or sustained overuse. Decide how clients are identified and where counters are stored. |
Response Rate Limiting (response-ratelimiting) |
Updates quotas using custom headers returned by the upstream response. | Different operations consume different quota amounts and the upstream service can report each request's cost. |
Request Size Limiting (request-size-limiting) |
Rejects request bodies larger than the configured size. | Large uploads or payloads could exhaust resources or violate an API contract. |
Request Termination (request-termination) |
Stops matching requests and returns a configured status code, message, or body without calling the upstream service. | An API, route, or consumer must be temporarily blocked or replaced with a maintenance response. |
Proxy Cache (proxy-cache) |
Stores eligible upstream responses and serves later matching requests from cache. | Repeated safe requests can tolerate cached data and reduced upstream load is valuable. Check methods, status codes, content types, and cache lifetime. |
For the portal's dedicated service rate-limit page, see Rate Limiting.
Serverless plugins¶
| Plugin | What it does | Use it when |
|---|---|---|
AWS Lambda (aws-lambda) |
Invokes an AWS Lambda function from gateway request processing. | A Lambda function supplies or extends the API implementation. Prefer an IAM role over static AWS keys where the environment supports it. |
Pre-Function (pre-function) |
Runs custom Lua code during selected phases before normal plugin processing completes. | A small gateway behaviour cannot be achieved safely with a standard plugin. Custom code can affect every matching request and requires specialist review. |
Post-Function (post-function) |
Runs custom Lua code during selected phases after normal plugin processing. | Approved custom behaviour must run later in the plugin sequence. Apply the same code-review and testing controls as application code. |
Azure Functions (azure-functions) |
Invokes an Azure Function and proxies the function response. | An Azure Function is used as the serverless upstream and gateway security or traffic plugins are also needed. |
Analytics and Monitoring plugins¶
These plugins publish operational data. They do not replace alert rules, dashboards, destination retention, or access controls.
| Plugin | What it does | Use it when |
|---|---|---|
Datadog (datadog) |
Sends gateway metrics to a Datadog agent. | Datadog is the approved monitoring platform and gateway traffic must appear in its dashboards and alerts. |
Prometheus (prometheus) |
Exposes Kong and proxied-upstream metrics in Prometheus exposition format. | A Prometheus-compatible collector will scrape gateway metrics. Control access to the metrics endpoint. |
Zipkin (zipkin) |
Creates or propagates distributed tracing spans and reports them to a Zipkin-compatible collector. | A request must be traced across the gateway and downstream services. Align sampling and trace headers across systems. |
StatsD (statsd) |
Sends selected gateway metrics to a StatsD server. | The monitoring stack accepts StatsD counters, gauges, timers, or related metrics. |
Transformation plugins¶
| Plugin | What it does | Use it when |
|---|---|---|
Request Transformer (request-transformer) |
Adds, removes, renames, or replaces request headers, query parameters, and body fields before the upstream call. | The client request must be adapted to the upstream contract. Do not use it to hide an undocumented breaking change. |
Response Transformer (response-transformer) |
Adds, removes, renames, or replaces response headers and JSON body fields before returning the response. | The upstream response needs a controlled compatibility or security adjustment. |
Correlation ID (correlation-id) |
Generates or forwards a unique request identifier and can return it to the client. | Logs and traces from several systems must be connected to one request. Standardise the header name across services. |
gRPC-Gateway (grpc-gateway) |
Transcodes REST-style JSON requests into gRPC calls using an annotated Protobuf definition. | HTTP/JSON clients must call an upstream gRPC service. The matching .proto definition is required. |
gRPC-Web (grpc-web) |
Translates between browser-compatible gRPC-Web traffic and an upstream gRPC service. | Browser JavaScript applications need direct access to a gRPC service. |
Logging plugins¶
Logging plugins send request and response records to different destinations. Logs can contain IP addresses, paths, headers, consumer identifiers, and other sensitive information. Apply approved redaction, transport security, access, and retention controls.
| Plugin | What it does | Use it when |
|---|---|---|
TCP Log (tcp-log) |
Sends request and response log records to a TCP server. | The logging receiver requires reliable connection-oriented transport. |
UDP Log (udp-log) |
Sends log records to a UDP server without delivery acknowledgement. | Low-overhead delivery is preferred and occasional packet loss is acceptable. |
HTTP Log (http-log) |
Sends log records to an HTTP endpoint. | A log collector exposes an approved HTTP ingestion API. Configure TLS, authentication headers, timeouts, and batching carefully. |
File Log (file-log) |
Appends request and response records to a file on the gateway node. | A node-local file is explicitly required and log rotation/collection is configured. This is less suitable for ephemeral or multi-node environments. |
Syslog (syslog) |
Sends request and response records to a syslog destination. | The organisation uses a syslog-based logging or SIEM pipeline. |
Loggly (loggly) |
Sends structured request and response data to Loggly. | Loggly is the approved central log platform and the required customer token and transport are available. |
Custom Obsidian plugins¶
The following plugins are implemented for Obsidian and are not standard Kong Plugin Hub entries.
| Plugin | Current behaviour visible in the portal | Use it when |
|---|---|---|
Service Limit (service-limit) |
Applies daily and/or monthly byte, kilobyte, megabyte, or gigabyte allowances to one service. It can count by service or by service and user, use campaign limits, alert at thresholds, block with 429, redirect with 301, or use a soft limit. It supports local/Redis state and optional Lambda actions when limits are reached or released. |
One service requires data allowances or user/campaign-specific controls. See Service Limits. |
Global Limit (global-limit) |
Applies an aggregate daily and/or monthly data allowance across the services associated with an entity. It supports threshold email alerts, soft/block/redirect actions, local/Redis state, fault-tolerance choices, and optional Lambda actions. | An entity needs one overall data allowance rather than separate independent limits for each service. See Entity Limits. |
The descriptions above reflect the current portal forms and need confirmation from the Obsidian product owner, particularly the exact aggregation, reset, redirect, and limit-released behaviour.
Choosing between similar plugins¶
| Need | Usually start with |
|---|---|
| Identify a machine with a simple credential | Key Auth |
| Identify an end user or client with signed tokens | JWT or the approved OAuth 2.0 design |
| Allow only selected authenticated groups | Authentication plugin plus ACL |
| Restrict requests by network | IP Restriction |
| Control requests per second/minute/day | Rate Limiting |
| Consume a quota reported by the upstream | Response Rate Limiting |
| Control transferred data per service or entity | Custom Service Limit or Global Limit |
| Adapt request or response fields | Request or Response Transformer |
| Trace one request across services | Correlation ID, optionally with Zipkin |
| Record request/response metadata | The logging plugin matching the approved collector |
Edit, disable, or delete a plugin¶
- Edit changes the active configuration at its current scope.
- OFF preserves the configuration but stops it from running. This is normally safer than deletion when testing or troubleshooting.
- Delete permanently removes the configuration.
Before changing an authentication or security plugin, confirm that another control will continue protecting the resource. Before changing a transformation, logging destination, cache, or serverless function, test both successful and failed requests.
Troubleshooting¶
A plugin is not affecting a request¶
- Confirm that it is switched ON.
- Confirm that the request matches the plugin's service, route, consumer, or global scope.
- Check whether another plugin configuration overlaps with it.
- Verify the protocol and plugin-specific matching fields.
- Check Audit Logs and gateway logs for recent changes or runtime errors.
Requests fail immediately after enabling a plugin¶
- Switch the new plugin off if the approved rollback plan allows it.
- Record the status code, response body, request ID, route, service, and time.
- Check credentials, required headers, destinations, and plugin-specific validation.
- Confirm that upstream requests still work without the new behaviour.
- Escalate with redacted evidence; never include passwords, API secrets, private keys, or AWS secret keys.
Warning
Adding a plugin from the main Plugins page makes it global. Use a service, route, or consumer page when only that resource needs the behaviour.
The plugin catalogue and technical behaviour are based on the portal's available-plugin configuration and the official Kong Plugin Hub. Availability and form options can depend on the Kong Gateway version and Obsidian environment.