OAuth 2.0 Introspection plugin

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

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}`.

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

OAuth2 Introspection 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.

Upstream headers

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.

About this Plugin
Plugin Version	0.5.4
Made by	Kong Inc.
Categories	Authentication
DB-less compatible?	Yes
Konnect Cloud compatible?	See latest plugin version
Compatible protocols	`http` `https` `grpc` `grpcs`