You are browsing documentation for an outdated plugin version.
Configuration
This plugin is compatible with DB-less mode.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
-
string required
The name of the plugin, in this case
oauth2-introspection
.- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
name
. - If using the KongPlugin object in Kubernetes, the field is
plugin
.
- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
-
string
The name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level
/plugins
endpoint. Not required if using/services/{serviceName|Id}/plugins
. -
string
The name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level
/plugins
endpoint. Not required if using/routes/{routeName|Id}/plugins
. -
boolean default:
true
Whether this plugin will be applied.
-
record required
-
string required
The full URL to the third-party introspection endpoint.
If the introspection endpoint is
https
,lua_ssl_trusted_certificate
must be set inkong.conf
to ensure the plugin can connect to the endpoint. The CA bundle file location depends on your OS. See the configuration reference for a list.Starting with Kong v2.2, users can set
lua_ssl_trusted_certificate=system
to automatically use the CA bundle from the OS.
-
number default:
30
The TTL in seconds for the introspection response. Set to 0 to disable the expiration.
-
string
The
token_type_hint
value to associate to introspection requests.
-
string required
The value to set as the
Authorization
header when querying the introspection endpoint. This depends on the OAuth 2.0 server, but usually is theclient_id
andclient_secret
as a Base64-encoded Basic Auth string (Basic MG9hNWl...
).
-
integer default:
10000
An optional timeout in milliseconds when sending data to the upstream server.
-
integer default:
60000
An optional value in milliseconds that defines how long an idle connection lives before being closed.
-
boolean required default:
false
A boolean indicating whether to forward information about the current downstream request to the introspect endpoint. If true, headers
X-Request-Path
andX-Request-Http-Method
will be inserted into the introspect request.
-
boolean default:
false
An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by Kong before proxying the request.
-
boolean default:
true
A boolean value that indicates whether the plugin should run (and try to authenticate) on
OPTIONS
preflight requests. If set tofalse
, thenOPTIONS
requests will always be allowed.
-
string len_min:
0
An optional string (consumer UUID) value to use as an anonymous consumer if authentication fails. If empty (default), the request fails with an authentication failure
4xx
.
-
string required default:
username
Must be one of:username
,client_id
A string indicating whether to associate OAuth2
username
orclient_id
with the consumer’s username. OAuth2username
is mapped to a consumer’susername
field, while an OAuth2client_id
maps to a consumer’scustom_id
.
-
map required
A list of custom headers to be added in the introspection request.
-
set of type
string
requiredA list of custom claims to be forwarded from the introspection response to the upstream request. Claims are forwarded in headers with prefix
X-Credential-{claim-name}
.
-