Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

OAuth 2.0 Introspection

By
Available in the Kong Konnect app
Available with Kong Gateway Enterprise subscription - Contact Sales
You are browsing documentation for an outdated plugin version.

Looking for the plugin's configuration parameters? You can find them in the OAuth 2.0 Introspection configuration reference doc.

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.

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.