Validate access tokens sent by developers using a third-party OAuth 2.0
Authorization Server by leveraging its introspection endpoint
(RFC 7662). This plugin assumes that
the consumer already has an access token that will be validated against a
third-party OAuth 2.0 server.
Note: The OpenID Connect Plugin supports
OAuth 2.0 Token Introspection as well and offers functionality beyond
this plugin, such as restricting access by scope.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway
declaratively.
Therefore, the Admin API is mostly read-only. The only tasks it can perform are all
related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Example plugin configuration
Enable on a service
Enable on a route
Enable globally
The following examples provide some typical configurations for enabling
the oauth2-introspection
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=oauth2-introspection" \
--data "config.introspection_url=https://example-url.com" \
--data "config.authorization_value=Basic MG9hNWlpbjpPcGVuU2VzYW1l" \
--data "config.consumer_by=username"
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: oauth2-introspection-example
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
plugin: oauth2-introspection
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: oauth2-introspection-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: oauth2-introspection
service: SERVICE_NAME|SERVICE_ID
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the OAuth 2.0 Introspection plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Introspection Url:
https://example-url.com
- Config.Authorization Value:
Basic MG9hNWlpbjpPcGVuU2VzYW1l
- Config.Consumer By:
username
- Click Create.
The following examples provide some typical configurations for enabling
the oauth2-introspection
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=oauth2-introspection" \
--data "config.introspection_url=https://example-url.com" \
--data "config.authorization_value=Basic MG9hNWlpbjpPcGVuU2VzYW1l" \
--data "config.consumer_by=username"
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: oauth2-introspection-example
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
plugin: oauth2-introspection
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: oauth2-introspection-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: oauth2-introspection
route: ROUTE_NAME
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the OAuth 2.0 Introspection plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Introspection Url:
https://example-url.com
- Config.Authorization Value:
Basic MG9hNWlpbjpPcGVuU2VzYW1l
- Config.Consumer By:
username
- Click Create.
A plugin which is not associated to any service, route, or consumer is
considered global, and will be run on every request. Read the
Plugin Reference and the Plugin Precedence
sections for more information.
The following examples provide some typical configurations for enabling
the oauth2-introspection
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=oauth2-introspection" \
--data "config.introspection_url=https://example-url.com" \
--data "config.authorization_value=Basic MG9hNWlpbjpPcGVuU2VzYW1l" \
--data "config.consumer_by=username"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-oauth2-introspection>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
plugin: oauth2-introspection
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: oauth2-introspection
config:
introspection_url: https://example-url.com
authorization_value: Basic MG9hNWlpbjpPcGVuU2VzYW1l
consumer_by: username
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the OAuth 2.0 Introspection plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, set the plugin scope to Global.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Introspection Url:
https://example-url.com
- Config.Authorization Value:
Basic MG9hNWlpbjpPcGVuU2VzYW1l
- Config.Consumer By:
username
- Click Create.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter |
Description |
name
required
Type: string
|
The name of the plugin, in this case oauth2-introspection . |
service.name or service.id
optional
Type: 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/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
optional
Type: 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/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
optional
Type: boolean
Default value: true
|
Whether this plugin will be applied. |
config.introspection_url
required
Type: string
|
The full URL to the third-party introspection endpoint.
If the introspection endpoint is https , lua_ssl_trusted_certificate
must be set in kong.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.
|
config.authorization_value
required
Type: string
|
The value to set as the Authorization header when querying the introspection endpoint. This depends on the OAuth 2.0 server, but usually is the client_id and client_secret as a Base64-encoded Basic Auth string (Basic MG9hNWl... ).
|
config.token_type_hint
optional
Type: string
|
The token_type_hint value to associate to introspection requests.
|
config.ttl
optional
Type: number
Default value: 30
|
The TTL in seconds for the introspection response. Set to 0 to disable the expiration.
|
config.hide_credentials
required
Type: boolean
|
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.
|
config.timeout
optional
Type: integer
Default value: 10000
|
An optional timeout in milliseconds when sending data to the upstream server.
|
config.keepalive
optional
Type: integer
Default value: 60000
|
An optional value in milliseconds that defines how long an idle connection lives before being closed.
|
config.anonymous
optional
Type: string
|
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 .
|
config.run_on_preflight
optional
Type: boolean
Default value: true
|
A boolean value that indicates whether the plugin should run (and try to authenticate) on OPTIONS preflight requests. If set to false , then OPTIONS requests will always be allowed.
|
config.consumer_by
required
Type: string
Default value: CONSUMER_BY_DEFAULT
|
A string indicating whether to associate OAuth2 username or client_id
with the consumer’s username. OAuth2 username is mapped to a consumer’s
username field, while an OAuth2 client_id maps to a consumer’s
custom_id .
|
config.introspect_request
required
Type: boolean
Default value: false
|
A boolean indicating whether to forward information about the current
downstream request to the introspect endpoint. If true, headers
X-Request-Path and X-Request-Http-Method will be inserted into the
introspect request.
|
config.custom_introspection_headers
required
Type: map of string keys and string values
|
A list of custom headers to be added in the introspection request.
|
config.custom_claims_forward
required
Type: set of string elements
|
A 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} .
|
Flow

Associate the response to a consumer
To associate the introspection response resolution to a Kong consumer, provision a Kong consumer with the same username
returned by the Introspection Endpoint response.
When a client has been authenticated, the plugin appends the following headers to the request before proxying it to the upstream API/microservice.
Use these headers to identify the consumer in your code:
X-Consumer-ID
, the ID of the consumer on Kong (if matched)
X-Consumer-Custom-ID
, the custom_id
of the consumer (if matched and if existing)
X-Consumer-Username
, the username of
the consumer (if matched and if existing)
X-Anonymous-Consumer
, set to true if authentication fails, and the anonymous
consumer is set instead.
X-Credential-Scope
, as returned by the Introspection response (if any)
X-Credential-Client-ID
, as returned by the Introspection response (if any)
X-Credential-Identifier
, as returned by the Introspection response (if any)
X-Credential-Token-Type
, as returned by the Introspection response (if any)
X-Credential-Exp
, as returned by the Introspection response (if any)
X-Credential-Iat
, as returned by the Introspection response (if any)
X-Credential-Nbf
, as returned by the Introspection response (if any)
X-Credential-Sub
, as returned by the Introspection response (if any)
X-Credential-Aud
, as returned by the Introspection response (if any)
X-Credential-Iss
, as returned by the Introspection response (if any)
X-Credential-Jti
, as returned by the Introspection response (if any)
Additionally, any claims specified in config.custom_claims_forward
are also forwarded with the X-Credential-
prefix.
Note: If authentication fails, the plugin doesn’t set any X-Credential-*
headers.
It appends X-Anonymous-Consumer: true
and sets the anonymous
consumer instead.
Changelog
Kong Gateway 3.0.x
- The deprecated
X-Credential-Username
header has been removed.