Upstream OAuth

Enterprise only

Overview Examples Guides Configuration reference Changelog

How it works

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

Authentication methods

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

Caching

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.

Using cloud authentication with Redis v3.13+

If your plugin uses a Redis datastore, you can authenticate to it with a cloud Redis provider, or with an OAuth 2.0 token endpoint. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

AWS ElastiCache
Azure Managed Redis
Google Cloud Memorystore (with or without Valkey)
OAuth 2.0 v3.16+, using the client_credentials or password grant type

Each cloud provider also supports an instance and cluster configuration.

You need:

A running Redis instance on an AWS ElastiCache instance for Valkey 7.2 or later or ElastiCache for Redis OSS version 7.0 or later
The ElastiCache user needs to set “Authentication mode” to “IAM”

The following policy assigned to the IAM user/IAM role that is used to connect to the ElastiCache:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "elasticache:Connect"
            ],
            "Resource": [
                "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE",
                "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE_USER"
            ]
        }
    ]
}

Copied!

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: aws
        aws_cache_name: $AWS_CACHE_NAME
        aws_is_serverless: false
        aws_region: $AWS_REGION
        aws_access_key_id: $AWS_ACCESS_KEY_ID
        aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The ElastiCache instance address.
$INSTANCE_USERNAME: The ElastiCache username with IAM Auth mode configured.
$AWS_CACHE_NAME: Name of your AWS ElastiCache instance.
$AWS_REGION: Your AWS ElastiCache instance region.
$AWS_ACCESS_KEY_ID: (Optional) Your AWS access key ID.
$AWS_ACCESS_SECRET_KEY: (Optional) Your AWS secret access key.

You need:

A running Redis instance on an AWS ElastiCache cluster for Valkey 7.2 or later or ElastiCache for Redis OSS version 7.0 or later
The ElastiCache user needs to set “Authentication mode” to “IAM”

The following policy assigned to the IAM user/IAM role that is used to connect to the ElastiCache:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "elasticache:Connect"
            ],
            "Resource": [
                "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE",
                "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE_USER"
            ]
        }
    ]
}

Copied!

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      username: $CLUSTER_USERNAME
      port: 6379
      cloud_authentication:
        auth_provider: aws
        aws_cache_name: $AWS_CACHE_NAME
        aws_is_serverless: false
        aws_region: $AWS_REGION
        aws_access_key_id: $AWS_ACCESS_KEY_ID
        aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

Copied!

Replace the following with your actual values:

$CLUSTER_ADDRESS: The ElastiCache cluster address.
$CLUSTER_USERNAME: The ElastiCache username with IAM Auth mode configured.
$AWS_CACHE_NAME: Name of your AWS ElastiCache cluster.
$AWS_REGION: Your AWS ElastiCache cluster region.
$AWS_ACCESS_KEY_ID: (Optional) Your AWS access key ID.
$AWS_ACCESS_SECRET_KEY: (Optional) Your AWS secret access key.

You need:

A running Redis instance on an Azure Managed Redis instance with Entra authentication configured
Add the user/service principal/identity to the “Microsoft Entra Authentication Redis user” list for the Azure Managed Redis instance

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      username: $INSTANCE_USERNAME
      port: 10000
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The Azure Managed Redis instance address.
$INSTANCE_USERNAME: The object (principal) ID of the Principal/Identity with essential access.
$AZURE_CLIENT_ID: The client ID of the Principal/Identity.
$AZURE_CLIENT_SECRET: (Optional) The client secret of the Principal/Identity.
$AZURE_TENANT_ID: (Optional) The tenant ID of the Principal/Identity.

You need:

A running Redis instance on an Azure Managed Redis cluster with Entra authentication configured
Add the user/service principal/identity to the “Microsoft Entra Authentication Redis user” list for the Azure Managed Redis instance

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 10000
      username: $CLUSTER_USERNAME
      port: 10000
      cloud_authentication:
        auth_provider: azure
        azure_client_id: $AZURE_CLIENT_ID
        azure_client_secret: $AZURE_CLIENT_SECRET
        azure_tenant_id: $AZURE_TENANT_ID

Copied!

Replace the following with your actual values:

$CLUSTER_ADDRESS: The Azure Managed Redis cluster address.
$CLUSTER_USERNAME: The object (principal) ID of the Principal/Identity with essential access.
$AZURE_CLIENT_ID: The client ID of the Principal/Identity.
$AZURE_CLIENT_SECRET: (Optional) The client secret of the Principal/Identity.
$AZURE_TENANT_ID: (Optional) The tenant ID of the Principal/Identity.

You need:

A running Redis instance on an Google Cloud Memorystore instance
Assign the principal to the corresponding role:
- Cloud Memorystore Redis DB Connection User(roles/redis.dbConnectionUser) for Memorystore for Redis Cluster
- Memorystore DB Connector User (roles/memorystore.dbConnectionUser) for Memorystore for Valkey

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The Memorystore instance address.
$GCP_SERVICE_ACCOUNT: (Optional) The GCP service account JSON.

You need:

A running Redis instance on an Google Cloud Memorystore cluster
Assign the principal to the corresponding role:
- Cloud Memorystore Redis DB Connection User(roles/redis.dbConnectionUser) for Memorystore for Redis Cluster
- Memorystore DB Connector User (roles/memorystore.dbConnectionUser) for Memorystore for Valkey

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      cluster_nodes:
      - ip: $CLUSTER_ADDRESS
        port: 6379
      port: 6379
      cloud_authentication:
        auth_provider: gcp
        gcp_service_account_json: $GCP_SERVICE_ACCOUNT

Copied!

Replace the following with your actual values:

$CLUSTER_ADDRESS: The Memorystore cluster address.
$GCP_SERVICE_ACCOUNT: The GCP service account JSON.

You need:

An OAuth 2.0 token endpoint that issues access tokens for the client_credentials or password grant type
A Redis deployment that accepts the issued access token as a bearer credential, either natively or through an OAuth-aware proxy (such as Envoy) placed in front of it

To configure OAuth 2.0 authentication with Redis, add the following parameters to your plugin configuration:

config:
  cache:
    strategy: redis
    redis:
      host: $INSTANCE_ADDRESS
      port: 6379
      cloud_authentication:
        auth_provider: oauth
        oauth:
          token_endpoint: $OAUTH_TOKEN_ENDPOINT
          grant_type: client_credentials
          client_id: $OAUTH_CLIENT_ID
          client_secret: $OAUTH_CLIENT_SECRET

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The Redis instance or proxy address.
$OAUTH_TOKEN_ENDPOINT: The OAuth 2.0 token endpoint URL used to request access tokens.
$OAUTH_CLIENT_ID: Your OAuth 2.0 client ID.
$OAUTH_CLIENT_SECRET: Your OAuth 2.0 client secret.

Kong Gateway caches the acquired token for the duration of its validity and refreshes it asynchronously before it expires. To use the password grant type instead, set oauth.grant_type to password and also provide oauth.username and oauth.password.

If your Redis deployment uses ACL-based authentication and needs a username sent alongside the token, also set one of:

oauth.redis_username: a static username to send with AUTH <username> <token>.
oauth.redis_username_claim: the name of a claim in the access token (for example, oid for Microsoft Entra ID) to derive the username from.

Upstream OAuth

How it works

Authentication methods

Caching

Caching strategies

Using cloud authentication with Redis v3.13+

Help us make these docs great!

Still need help?