Upstream OAuth

The Upstream OAuth plugin allows Kong Gateway to support OAuth flows between Kong Gateway and the upstream API.

The plugin supports storing tokens issued by the IdP in different backend formats.

The upstream OAuth2 credential flow works similarly to the client credentials grant used by the OpenID Connect plugin. If a cached access token isn’t found, Kong Gateway issues a request to the IdP token endpoint to obtain a new token, which is cached, and then passed to the upstream API via a configurable header (Authorization by default).

 
sequenceDiagram
    autonumber
    participant client as Client 
(e.g. mobile app)
    participant kong as API Gateway 
(Kong Gateway)
    participant idp as IdP 
(e.g. Keycloak)
    participant api as 3rd Party API
    activate client
    activate kong
    client->>kong: request to Kong Gateway
    deactivate client
    activate idp
    kong->>idp: request access token 
from IdP using 
client ID and client secret (if IdP auth is set)
    deactivate kong
    idp->>idp: authenticate client
    activate kong
    idp->>kong: return access token
    deactivate idp
    activate api
    kong->>api: request with access token 
in authorization header
    deactivate kong
    activate kong
    api->>kong: response
    deactivate api
    activate client
    kong->>client: response
    deactivate client
    deactivate kong
  

This plugin supports the following authentication methods:

• client_secret_basic: Send client_id and client_secret in an Authorization: Basic header
• client_secret_post: Send client_id and client_secret as part of the body
• client_secret_jwt: Send a JWT signed with the client_secret using the client assertion as part of the body

The Upstream OAuth plugin caches tokens returned by the IdP.
Cached entries expire based on the expires_in indicated by the IdP in the response to the token endpoint.

Tokens are cached using a hash of all values configured under the config.oauth key. This means that if two instances of the plugin (for example, configured on different Routes and Gateway Services) use identical values under the config.oauth section, then these will share cached tokens.

Caching strategies

The plugin supports the following caching strategies:

• memory: A locally stored lua_shared_dict. The default dictionary, kong_db_cache, is also used by other plugins and Kong Gateway elements to store unrelated database cache entities.
• redis: Supports Redis, Redis Cluster, and Redis Sentinel deployments.