OAuth 2.0 Introspection Configuration

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:

• name or plugin

  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.

• service.name or service.id

  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.

• route.name or route.id

  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.

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • introspection_url

    string required

    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.

  • ttl

    number default: 30

    The TTL in seconds for the introspection response. Set to 0 to disable the expiration.

  • token_type_hint

    string

    The token_type_hint value to associate to introspection requests.

  • authorization_value

    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 the client_id and client_secret as a Base64-encoded Basic Auth string (Basic MG9hNWl...).

  • timeout

    integer default: 10000

    An optional timeout in milliseconds when sending data to the upstream server.

  • keepalive

    integer default: 60000

    An optional value in milliseconds that defines how long an idle connection lives before being closed.

  • introspect_request

    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 and X-Request-Http-Method will be inserted into the introspect request.

  • hide_credentials

    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.

  • run_on_preflight

    boolean default: 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.

  • anonymous

    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.

  • consumer_by

    string required default: username Must be one of: username, client_id

    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.

  • custom_introspection_headers

    map required

    A list of custom headers to be added in the introspection request.

  • custom_claims_forward

    set of type string required

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