OAuth 2.0 Introspection plugin

IAM only: This plugin is only available with a IAM subscription.

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.

Terminology

plugin: a plugin executing actions inside IAM before or after a request has been proxied to the upstream API.
Service: the IAM entity representing an external upstream API or microservice.
Route: the IAM entity representing a way to map downstream requests to upstream services.
Consumer: the IAM entity representing a developer or machine using the API. When using IAM, a Consumer only communicates with IAM which proxies every call to the said upstream API.
Credential: a unique string associated with a Consumer, also referred to as an API key.
upstream service: this refers to your own API/service sitting behind IAM, to which client requests are forwarded.
API: a legacy entity used to represent your upstream services. Deprecated in favor of Services.

Configuration

Enabling the plugin on a Service

With a database

Configure this plugin on a Service by making the following request:

$ curl -X POST http://localhost:8001/services/{service}/plugins \
    --data "name=oauth2-introspection"  \
    --data "config.consumer_by=username"

Without a database

Configure this plugin on a Service by adding this section do your declarative configuration file:

plugins:
- name: oauth2-introspection
  service: {service}
  config:
    consumer_by: username

In both cases, {service} is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

With a database

Configure this plugin on a Route with:

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
    --data "name=oauth2-introspection"  \
    --data "config.consumer_by=username"

Without a database

Configure this plugin on a Route by adding this section do your declarative configuration file:

plugins:
- name: oauth2-introspection
  route: {route}
  config:
    consumer_by: username

In both cases, {route} is the id or name of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

With a database

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://localhost:8001/consumers/{consumer}/plugins \
    --data "name=oauth2-introspection" \
     \
    --data "config.consumer_by=username"

Without a database

Configure this plugin on a Consumer by adding this section do your declarative configuration file:

plugins:
- name: oauth2-introspection
  consumer: {consumer}
  config:
    consumer_by: username

In both cases, {consumer} is the id or username of the Consumer that this plugin configuration will target.

You can combine consumer_id and service_id

in the same request, to furthermore narrow the scope of the plugin.

Global plugins

Using a database, all plugins can be configured using the http://localhost:8001/plugins/ endpoint.
Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of IAM) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

form parameter	description
`name`	The name of the plugin to use, in this case `oauth2-introspection`
`service_id`	The id of the Service which this plugin will target.
`route_id`	The id of the Route which this plugin will target.
`enabled` default value: `true`	Whether this plugin will be applied.
`consumer_id`	The id of the Consumer which this plugin will target.
`api_id`	The id of the API which this plugin will target. Note: The API Entity is deprecated in favor of Services.
`config.introspection_url`	The full URL to the third-party introspection endpoint
`config.authorization_value`	The value to append to the Authorization header when requesting the introspection endpoint
`config.token_type_hint` optional	The token_type_hint value to associate to introspection requests
`config.ttl` optional default value: 60	The TTL in seconds for the introspection response - set to 0 to disable the expiration
`config.hide_credentials` optional	An optional boolean value telling the plugin to hide the credential to the upstream API server. It will be removed by IAM before proxying the request.
`config.timeout` optional default value: 10000	An optional timeout in milliseconds when sending data to the upstream server
`config.keepalive` optional default value: 60000	An optional value in milliseconds that defines for how long an idle connection will live before being closed
`config.anonymous` optional	An optional string (consumer uuid) value to use as an “anonymous” consumer if authentication fails. If empty (default), the request will fail with an authentication failure 4xx.
`config.run_on_preflight` optional 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` optional default value: username	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` optional 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 in the introspect request
`config.custom_introspection_headers` optional	A list of custom headers to be added in the introspection request
`config.custom_claims_forward` optional	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 an IAM Consumer, you will have to provision an IAM Consumer with the same username returned by the Introspection Endpoint response.

Upstream Headers

When a client has been authenticated, the plugin will append some headers to the request before proxying it to the upstream API/Microservice, so that you can identify the consumer in your code:

X-Consumer-ID, the ID of the Consumer on IAM (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, will be set to true when authentication failed, and the ‘anonymous' consumer was 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-Username, 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 will also be forwarded with the X-Credential- prefix.

Note: Aforementioned X-Credential-* headers are not set when authentication failed, and the ‘anonymous' consumer was set instead.