OAuth 2.0 Introspection

You can 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.

1. The client uses the third-party OAuth 2.0 server to generate an access token, and uses it to make a request through Kong Gateway.
2. The third-party OAuth 2.0 server leverages the OAuth 2.0 Introspection plugin to validate the client’s access token.
3. If the token is valid, Kong Gateway proxies the request to the upstream service, which sends the response back to the client through Kong Gateway.

 
sequenceDiagram
    autonumber
    participant client as Client
    participant oauth as OAuth 2.0 server
    participant kong as Kong Gateway with 
 Introspection plugin
    participant upstream as Upstream service
    activate client
    activate oauth
    client->>oauth: request access token
    oauth->>client: generate access token
    activate kong
    client->>kong: send request with
access token
    deactivate client
    kong->>oauth: send access token 
for verification
    oauth->>kong: verify access token
    activate upstream
    kong->>upstream: send request with
access token
    upstream->>kong: response
    deactivate upstream
    activate client
    kong->>client: response
    deactivate kong
    deactivate client
  

To associate the introspection response resolution with a Kong Gateway Consumer, provision the Consumer with the same username as the one 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 Gateway (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.