You are browsing unreleased documentation.
Configuration
This plugin is compatible with DB-less mode.
Compatible protocols
The Upstream OAuth plugin is compatible with the following protocols:
grpc
, grpcs
, http
, https
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
-
name or plugin
string requiredThe name of the plugin, in this case
upstream-oauth
.- 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
.
- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
-
instance_name
stringAn optional custom name to identify an instance of the plugin, for example
upstream-oauth_my-service
.The instance name shows up in Kong Manager and in Konnect, so it's useful when running the same plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance via the Kong Admin API.
An instance name must be unique within the following context:
- Within a workspace for Kong Gateway Enterprise
- Within a control plane or control plane group for Konnect
- Globally for Kong Gateway (OSS)
-
service.name or service.id
stringThe 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
stringThe 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
. -
consumer.name or consumer.id
stringThe name or ID of the consumer the plugin targets. Set one of these parameters if adding the plugin to a consumer through the top-level
/plugins
endpoint. Not required if using/consumers/{consumerName|Id}/plugins
. -
consumer_group.name or consumer_group.id
stringThe name or ID of the consumer group the plugin targets. If set, the plugin will activate only for requests where the specified group has been authenticated
/plugins
endpoint. Not required if using/consumer_groups/{consumerGroupName|Id}/plugins
. -
enabled
boolean default:true
Whether this plugin will be applied.
-
config
record required-
client
record required-
auth_method
string required default:client_secret_post
Must be one of:client_secret_post
,client_secret_basic
,client_secret_jwt
,none
The authentication method used in client requests to the IdP. Supported values are:
client_secret_basic
to sendclient_id
andclient_secret
in theAuthorization: Basic
header,client_secret_post
to sendclient_id
andclient_secret
as part of the request body, orclient_secret_jwt
to send a JWT signed with theclient_secret
using the client assertion as part of the body.
-
client_secret_jwt_alg
string required default:HS512
Must be one of:HS512
,HS256
The algorithm to use with JWT when using
client_secret_jwt
authentication.
-
http_version
number default:1.1
The HTTP version used for requests made by this plugin. Supported values:
1.1
for HTTP 1.1 and1.0
for HTTP 1.0.
-
http_proxy
stringThe proxy to use when making HTTP requests to the IdP.
-
http_proxy_authorization
stringThe
Proxy-Authorization
header value to be used withhttp_proxy
.
-
https_proxy
stringThe proxy to use when making HTTPS requests to the IdP.
-
https_proxy_authorization
stringThe
Proxy-Authorization
header value to be used withhttps_proxy
.
-
no_proxy
stringA comma-separated list of hosts that should not be proxied.
-
timeout
integer required default:10000
between:0
2147483646
Network I/O timeout for requests to the IdP in milliseconds.
-
keep_alive
boolean required default:true
Whether to use keepalive connections to the IdP.
-
ssl_verify
boolean default:false
Whether to verify the certificate presented by the IdP when using HTTPS.
-
-
oauth
record required-
token_endpoint
string requiredThe token endpoint URI.
-
token_headers
mapExtra headers to be passed in the token endpoint request.
-
token_post_args
mapExtra post arguments to be passed in the token endpoint request.
-
grant_type
string required default:client_credentials
Must be one of:client_credentials
,password
The OAuth grant type to be used.
-
client_id
string referenceable encryptedThe client ID for the application registration in the IdP.
-
client_secret
string referenceable encryptedThe client secret for the application registration in the IdP.
-
username
string referenceable encryptedThe username to use if
config.oauth.grant_type
is set topassword
.
-
password
string referenceable encryptedThe password to use if
config.oauth.grant_type
is set topassword
.
-
scopes
array of typestring
default:openid
List of scopes to request from the IdP when obtaining a new token.
-
audience
array of typestring
List of audiences passed to the IdP when obtaining a new token.
-
-
cache
record required-
strategy
string required default:memory
Must be one of:memory
,redis
The method Kong should use to cache tokens issued by the IdP.
-
memory
record required-
dictionary_name
string required default:kong_db_cache
The shared dictionary used by the plugin to cache tokens if
config.cache.strategy
is set tomemory
.
-
-
redis
record required-
host
stringA string representing a host name, such as example.com.
-
port
integer between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
connect_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
send_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
read_timeout
integer default:2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
username
string referenceableUsername to use for Redis connections. If undefined, ACL authentication won’t be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to
default
.
-
password
string referenceable encryptedPassword to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
-
sentinel_username
string referenceableSentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
-
sentinel_password
string referenceable encryptedSentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
-
database
integer default:0
Database to use for the Redis connection when using the
redis
strategy
-
keepalive_pool_size
integer default:256
between:1
2147483646
The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither
keepalive_pool_size
norkeepalive_backlog
is specified, no pool is created. Ifkeepalive_pool_size
isn’t specified butkeepalive_backlog
is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.
-
keepalive_backlog
integer between:0
2147483646
Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return
nil
. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less thankeepalive_pool_size
. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger thankeepalive_pool_size
.
-
sentinel_master
stringSentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
-
sentinel_role
string Must be one of:master
,slave
,any
Sentinel role to use for Redis connections when the
redis
strategy is defined. Defining this value implies using Redis Sentinel.
-
sentinel_nodes
array of typerecord
len_min:1
Sentinel node addresses to use for Redis connections when the
redis
strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.-
host
string required default:127.0.0.1
A string representing a host name, such as example.com.
-
port
integer default:6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
-
cluster_nodes
array of typerecord
len_min:1
Cluster addresses to use for Redis connections when the
redis
strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.-
ip
string required default:127.0.0.1
A string representing a host name, such as example.com.
-
port
integer default:6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
-
ssl
boolean default:false
If set to true, uses SSL to connect to Redis.
-
ssl_verify
boolean default:false
If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure
lua_ssl_trusted_certificate
inkong.conf
to specify the CA (or server) certificate used by your Redis server. You may also need to configurelua_ssl_verify_depth
accordingly.
-
server_name
stringA string representing an SNI (server name indication) value for TLS.
-
cluster_max_redirections
integer default:5
Maximum retry attempts for redirection.
-
connection_is_proxied
boolean default:false
If the connection to Redis is proxied (e.g. Envoy), set it
true
. Set thehost
andport
to point to the proxy address.
-
-
eagerly_expire
integer required default:5
The number of seconds to eagerly expire a cached token. By default, a cached token expires 5 seconds before its lifetime as defined in
expires_in
.
-
default_ttl
number default:3600
The lifetime of a token without an explicit
expires_in
value.
-
-
behavior
record required-
upstream_access_token_header_name
string required default:Authorization
len_min:0
The name of the header used to send the access token (obtained from the IdP) to the upstream service.
-
idp_error_response_status_code
integer required default:502
between:500
599
The response code to return to the consumer if Kong fails to obtain a token from the IdP.
-
idp_error_response_content_type
string required default:application/json; charset=utf-8
len_min:0
The Content-Type of the response to return to the consumer if Kong fails to obtain a token from the IdP.
-
idp_error_response_message
string required default:Failed to authenticate request to upstream
len_min:0
The message to embed in the body of the response to return to the consumer if Kong fails to obtain a token from the IdP.
-
idp_error_response_body_template
string required default:{ "code": "{{status}}", "message": "{{message}}" }
len_min:0
The template to use to create the body of the response to return to the consumer if Kong fails to obtain a token from the IdP.
-
purge_token_on_upstream_status_codes
array of typeinteger
default:401
An array of status codes which will force an access token to be purged when returned by the upstream. An empty array will disable this functionality.
-
-