Home / Kong Plugin Hub
Edit
Report

Upstream OAuth

Overview Examples Configuration reference Changelog

Configuration

configobjectrequired
Hide Child Parameters
behaviorobject
Hide Child Parameters
idp_error_response_body_templatestring

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.

Default:{ "code": "{{status}}", "message": "{{message}}" }

>= 0 characters

idp_error_response_content_typestring

The Content-Type of the response to return to the consumer if Kong fails to obtain a token from the IdP.

Default:application/json; charset=utf-8

>= 0 characters

idp_error_response_messagestring

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.

Default:Failed to authenticate request to upstream

>= 0 characters

idp_error_response_status_codeinteger

The response code to return to the consumer if Kong fails to obtain a token from the IdP.

Default:502

>= 500<= 599

purge_token_on_upstream_status_codesarray[integer]

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.

Default:401

>= 100<= 599

upstream_access_token_header_namestring

The name of the header used to send the access token (obtained from the IdP) to the upstream service.

Default:Authorization

>= 0 characters

cacheobject
Hide Child Parameters
default_ttlnumber

The lifetime of a token without an explicit expires_in value.

Default:3600

>= 0

eagerly_expireinteger

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:5

>= -1

memoryobject
Hide Child Parameters
dictionary_namestring

The shared dictionary used by the plugin to cache tokens if config.cache.strategy is set to memory.

Default:kong_db_cache

redisobject
Hide Child Parameters
cluster_max_redirectionsinteger

Maximum retry attempts for redirection.

Default:5

cluster_nodesarray[object]

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.

>= 1 characters

Show Child Parameters
connect_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

connection_is_proxiedboolean

If the connection to Redis is proxied (e.g. Envoy), set it true. Set the host and port to point to the proxy address.

Default:false

databaseinteger

Database to use for the Redis connection when using the redis strategy

Default:0

hoststring

A string representing a host name, such as example.com.

Default:127.0.0.1

keepalive_backloginteger

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 than keepalive_pool_size. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than keepalive_pool_size.

>= 0<= 2147483646

keepalive_pool_sizeinteger

The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither keepalive_pool_size nor keepalive_backlog is specified, no pool is created. If keepalive_pool_size isn’t specified but keepalive_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.

Default:256

>= 1<= 2147483646

passwordstring

Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
This field is referenceable.
This field is encrypted.

portinteger

An integer representing a port number between 0 and 65535, inclusive.

Default:6379

>= 0<= 65535

read_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

send_timeoutinteger

An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.

Default:2000

>= 0<= 2147483646

sentinel_masterstring

Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.

sentinel_nodesarray[object]

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.

>= 1 characters

Show Child Parameters
sentinel_passwordstring

Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
This field is referenceable.
This field is encrypted.

sentinel_rolestring

Sentinel role to use for Redis connections when the redis strategy is defined. Defining this value implies using Redis Sentinel.

Allowed values:anymasterslave

sentinel_usernamestring

Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
This field is referenceable.

server_namestring

A string representing an SNI (server name indication) value for TLS.

sslboolean

If set to true, uses SSL to connect to Redis.

Default:false

ssl_verifyboolean

If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure lua_ssl_trusted_certificate in kong.conf to specify the CA (or server) certificate used by your Redis server. You may also need to configure lua_ssl_verify_depth accordingly.

Default:false

usernamestring

Username 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.
This field is referenceable.

strategystring

The method Kong should use to cache tokens issued by the IdP.

Allowed values:memoryredis

Default:memory

clientobject
Hide Child Parameters
auth_methodstring

The authentication method used in client requests to the IdP. Supported values are: client_secret_basic to send client_id and client_secret in the Authorization: Basic header, client_secret_post to send client_id and client_secret as part of the request body, or client_secret_jwt to send a JWT signed with the client_secret using the client assertion as part of the body.

Allowed values:client_secret_basicclient_secret_jwtclient_secret_postnone

Default:client_secret_post

client_secret_jwt_algstring

The algorithm to use with JWT when using client_secret_jwt authentication.

Allowed values:HS256HS512

Default:HS512

http_proxystring

The proxy to use when making HTTP requests to the IdP.

http_proxy_authorizationstring

The Proxy-Authorization header value to be used with http_proxy.

http_versionnumber

The HTTP version used for requests made by this plugin. Supported values: 1.1 for HTTP 1.1 and 1.0 for HTTP 1.0.

Default:1.1

https_proxystring

The proxy to use when making HTTPS requests to the IdP.

https_proxy_authorizationstring

The Proxy-Authorization header value to be used with https_proxy.

keep_aliveboolean

Whether to use keepalive connections to the IdP.

Default:true

no_proxystring

A comma-separated list of hosts that should not be proxied.

ssl_verifyboolean

Whether to verify the certificate presented by the IdP when using HTTPS.

Default:false

timeoutinteger

Network I/O timeout for requests to the IdP in milliseconds.

Default:10000

>= 0<= 2147483646

oauthobjectrequired
Hide Child Parameters
audiencearray[string]

List of audiences passed to the IdP when obtaining a new token.

Default:[]

client_idstring

The client ID for the application registration in the IdP.
This field is encrypted.
This field is referenceable.

client_secretstring

The client secret for the application registration in the IdP.
This field is encrypted.
This field is referenceable.

grant_typestring

The OAuth grant type to be used.

Allowed values:client_credentialspassword

Default:client_credentials

passwordstring

The password to use if config.oauth.grant_type is set to password.
This field is encrypted.
This field is referenceable.

scopesarray[string]

List of scopes to request from the IdP when obtaining a new token.

Default:openid

token_endpointstringrequired

The token endpoint URI.

token_headersobject

Extra headers to be passed in the token endpoint request.

* Additional properties are allowed.
token_post_argsobject

Extra post arguments to be passed in the token endpoint request.

* Additional properties are allowed.
usernamestring

The username to use if config.oauth.grant_type is set to password.
This field is encrypted.
This field is referenceable.

consumerobject

If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
consumer_groupobject

If set, the plugin will activate only for requests where the specified consumer group has been authenticated. (Note that some plugins can not be restricted to consumers groups this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer Groups

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
protocolsarray[string]

A set of strings representing HTTP protocols.

Allowed values:grpcgrpcshttphttps

Default:grpc, grpcs, http, https

routeobject

If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring
serviceobject

If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.

* Additional properties are NOT allowed.
Hide Child Parameters
idstring

Did this doc help?

Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support