Configuration
This plugin is compatible with DB-less mode.
Compatible protocols
The OpenID Connect 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:
-
string required
The name of the plugin, in this case
openid-connect
.- 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
-
string
An optional custom name to identify an instance of the plugin, for example
openid-connect_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)
-
string
The 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
. -
string
The 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
. -
boolean default:
true
Whether this plugin will be applied.
-
record required
-
string required
The discovery endpoint (or the issuer identifier). When there is no discovery endpoint, please also configure
config.using_pseudo_issuer=true
.
-
boolean default:
false
If the plugin uses a pseudo issuer. When set to true, the plugin will not discover the configuration from the issuer URL specified with
config.issuer
.
-
array of type
string
Extra header names passed to the discovery endpoint.
-
array of type
string
Extra header values passed to the discovery endpoint.
-
set of type
string
JWKS URIs whose public keys are trusted (in addition to the keys found with the discovery).
-
number default:
30
Specifies how long (in seconds) the plugin waits between discovery attempts. Discovery is still triggered on an as-needed basis.
-
array of type
string
default:password, client_credentials, authorization_code, bearer, introspection, userinfo, kong_oauth2, refresh_token, session
Must be one of:password
,client_credentials
,authorization_code
,bearer
,introspection
,userinfo
,kong_oauth2
,refresh_token
,session
Types of credentials/grants to enable.
-
array of type
string
referenceable encryptedThe client id(s) that the plugin uses when it calls authenticated endpoints on the identity provider.
-
array of type
string
referenceable encryptedThe client secret.
-
array of type
string
Must be one of:client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
,none
The default OpenID Connect client authentication method is ‘client_secret_basic’ (using ‘Authorization: Basic’ header), ‘client_secret_post’ (credentials in body), ‘client_secret_jwt’ (signed client assertion in body), ‘private_key_jwt’ (private key-signed assertion), ‘tls_client_auth’ (client certificate), ‘self_signed_tls_client_auth’ (self-signed client certificate), and ‘none’ (no authentication).
-
array of type
record
The JWK used for the private_key_jwt authentication.
-
string
-
string
-
string
-
array of type
string
-
string
-
string
-
string
-
array of type
string
-
string
-
string
-
string referenceable encrypted
-
string
-
string
-
string
-
string
-
string
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
string referenceable encrypted
-
-
array of type
string
Must be one of:HS256
,HS384
,HS512
,RS256
,RS384
,RS512
,ES256
,ES384
,ES512
,PS256
,PS384
,PS512
,EdDSA
The algorithm to use for client_secret_jwt (only HS***) or private_key_jwt authentication.
-
string default:
client_id
The client to use for this request (the selection is made with a request parameter with the same name).
-
array of type
string
The redirect URI passed to the authorization and token endpoints.
-
array of type
string
referenceableWhere to redirect the client when
login_action
is set toredirect
.
-
array of type
string
referenceableWhere to redirect the client after the logout.
-
array of type
string
Where to redirect the client on forbidden requests.
-
string default:
Forbidden
The error message for the forbidden requests (when not using the redirection).
-
boolean default:
true
Destroy any active session for the forbidden requests.
-
boolean default:
true
Destroy any active session for the unauthorized requests.
-
array of type
string
Where to redirect the client on unauthorized requests.
-
string default:
Unauthorized
The error message for the unauthorized requests (when not using the redirection).
-
array of type
string
Where to redirect the client when unexpected errors happen with the requests.
-
string default:
query
Must be one of:query
,form_post
,fragment
,query.jwt
,form_post.jwt
,fragment.jwt
,jwt
Response mode passed to the authorization endpoint: -
query
: for parameters in query string -form_post
: for parameters in request body -fragment
: for parameters in uri fragment (rarely useful as the plugin itself cannot read it) -query.jwt
,form_post.jwt
,fragment.jwt
: similar toquery
,form_post
andfragment
but the parameters are encoded in a JWT -jwt
: shortcut that indicates the default encoding for the requested response type.
-
array of type
string
default:code
The response type passed to the authorization endpoint.
-
array of type
string
referenceable default:openid
The scopes passed to the authorization and token endpoints.
-
array of type
string
The audience passed to the authorization endpoint.
-
array of type
string
The issuers allowed to be present in the tokens (
iss
claim).
-
array of type
string
The scopes (
scopes_claim
claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.
-
array of type
string
default:scope
The claim that contains the scopes. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
The audiences (
audience_claim
claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.
-
array of type
string
default:aud
The claim that contains the audience. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
The groups (
groups_claim
claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.
-
array of type
string
default:groups
The claim that contains the groups. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
The roles (
roles_claim
claim) required to be present in the access token (or introspection results) for successful authorization. This config parameter works in both AND / OR cases.
-
array of type
string
default:roles
The claim that contains the roles. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
The allowed values for the
hd
claim.
-
number
The maximum age (in seconds) compared to the
auth_time
claim.
-
array of type
string
The claim that contains authenticated groups. This setting can be used together with ACL plugin, but it also enables IdP managed groups with other applications and integrations. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
string
The pushed authorization endpoint. If set it overrides the value in
pushed_authorization_request_endpoint
returned by the discovery endpoint.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
,none
The pushed authorization request endpoint authentication method:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
, ornone
: do not authenticate
-
boolean
Forcibly enable or disable the pushed authorization requests. When not set the value is determined through the discovery using the value of
require_pushed_authorization_requests
(which defaults tofalse
).
-
boolean
Forcibly enable or disable the proof key for code exchange. When not set the value is determined through the discovery using the value of
code_challenge_methods_supported
, and enabled automatically (in case thecode_challenge_methods_supported
is missing, the PKCE will not be enabled).
-
boolean
Forcibly enable or disable the usage of signed request object on authorization or pushed authorization endpoint. When not set the value is determined through the discovery using the value of
require_signed_request_object
, and enabled automatically (in case therequire_signed_request_object
is missing, the feature will not be enabled).
-
string
The authorization endpoint. If set it overrides the value in
authorization_endpoint
returned by the discovery endpoint.
-
array of type
string
Extra query argument names passed to the authorization endpoint.
-
array of type
string
Extra query argument values passed to the authorization endpoint.
-
array of type
string
Extra query arguments passed from the client to the authorization endpoint.
-
number default:
600
Specifies how long the session used for the authorization code flow can be used in seconds until it needs to be renewed. 0 disables the checks and rolling.
-
string default:
authorization
The authorization cookie name.
-
string default:
/
starts_with:/
The authorization cookie Path flag.
-
string
The authorization cookie Domain flag.
-
string default:
Default
Must be one of:Strict
,Lax
,None
,Default
Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks.
-
boolean default:
true
Forbids JavaScript from accessing the cookie, for example, through the
Document.cookie
property.
-
boolean
Cookie is only sent to the server when a request is made with the https: scheme (except on localhost), and therefore is more resistant to man-in-the-middle attacks.
-
boolean default:
false
With this parameter, you can preserve request query arguments even when doing authorization code flow.
-
string
The token endpoint. If set it overrides the value in
token_endpoint
returned by the discovery endpoint.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
,none
The token endpoint authentication method:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
, ornone
: do not authenticate
-
array of type
string
Extra header names passed to the token endpoint.
-
array of type
string
Extra header values passed to the token endpoint.
-
array of type
string
Extra headers passed from the client to the token endpoint.
-
array of type
string
The names of token endpoint response headers to forward to the downstream client.
-
string
Add a prefix to the token endpoint response headers before forwarding them to the downstream client.
-
array of type
string
Must be one of:password
,client_credentials
,authorization_code
,refresh_token
Enable the sending of the token endpoint response headers only with certain grants: -
password
: with OAuth password grant -client_credentials
: with OAuth client credentials grant -authorization_code
: with authorization code flow -refresh_token
with refresh token grant.
-
array of type
string
Extra post argument names passed to the token endpoint.
-
array of type
string
Extra post argument values passed to the token endpoint.
-
array of type
string
Pass extra arguments from the client to the OpenID-Connect plugin. If arguments exist, the client can pass them using: - Query parameters - Request Body - Request Header This parameter can be used with
scope
values, like this:config.token_post_args_client=scope
In this case, the token would take thescope
value from the query parameter or from the request body or from the header and send it to the token endpoint.
-
string
The introspection endpoint. If set it overrides the value in
introspection_endpoint
returned by the discovery endpoint.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
,none
The introspection endpoint authentication method: :
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
, ornone
: do not authenticate
-
string default:
access_token
Introspection hint parameter value passed to the introspection endpoint.
-
boolean default:
true
Check that the introspection response has an
active
claim with a value oftrue
.
-
string default:
application/json
Must be one of:application/json
,application/token-introspection+jwt
,application/jwt
The value of
Accept
header for introspection requests: -application/json
: introspection response as JSON -application/token-introspection+jwt
: introspection response as JWT (from the current IETF draft document) -application/jwt
: introspection response as JWT (from the obsolete IETF draft document).
-
array of type
string
Extra header names passed to the introspection endpoint.
-
array of type
string
referenceable encryptedExtra header values passed to the introspection endpoint.
-
array of type
string
Extra headers passed from the client to the introspection endpoint.
-
array of type
string
Extra post argument names passed to the introspection endpoint.
-
array of type
string
Extra post argument values passed to the introspection endpoint.
-
array of type
string
Extra post arguments passed from the client to the introspection endpoint.
-
array of type
string
Extra post arguments passed from the client headers to the introspection endpoint.
-
boolean default:
false
Specifies whether to introspect the JWT access tokens (can be used to check for revocations).
-
string
The revocation endpoint. If set it overrides the value in
revocation_endpoint
returned by the discovery endpoint.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
,none
The revocation endpoint authentication method: :
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,tls_client_auth
,self_signed_tls_client_auth
, ornone
: do not authenticate
-
string
The end session endpoint. If set it overrides the value in
end_session_endpoint
returned by the discovery endpoint.
-
string
The user info endpoint. If set it overrides the value in
userinfo_endpoint
returned by the discovery endpoint.
-
string default:
application/json
Must be one of:application/json
,application/jwt
The value of
Accept
header for user info requests: -application/json
: user info response as JSON -application/jwt
: user info response as JWT (from the obsolete IETF draft document).
-
array of type
string
Extra header names passed to the user info endpoint.
-
array of type
string
Extra header values passed to the user info endpoint.
-
array of type
string
Extra headers passed from the client to the user info endpoint.
-
array of type
string
Extra query argument names passed to the user info endpoint.
-
array of type
string
Extra query argument values passed to the user info endpoint.
-
array of type
string
Extra query arguments passed from the client to the user info endpoint.
-
string
The token exchange endpoint.
-
string referenceable encrypted
The session secret.
-
string default:
default
The session audience, which is the intended target application. For example
"my-application"
.
-
string default:
session
The session cookie name.
-
boolean default:
false
Enables or disables persistent sessions.
-
string default:
remember
Persistent session cookie name. Use with the
remember
configuration parameter.
-
number default:
604800
Specifies how long the persistent session is considered valid in seconds. 0 disables the checks and rolling.
-
number default:
2592000
Limits how long the persistent session can be renewed in seconds, until re-authentication is required. 0 disables the checks.
-
number default:
900
Specifies how long the session can be inactive until it is considered invalid in seconds. 0 disables the checks and touching.
-
number default:
3600
Specifies how long the session can be used in seconds until it needs to be renewed. 0 disables the checks and rolling.
-
number default:
86400
Limits how long the session can be renewed in seconds, until re-authentication is required. 0 disables the checks.
-
string default:
/
starts_with:/
The session cookie Path flag.
-
string
The session cookie Domain flag.
-
string default:
Lax
Must be one of:Strict
,Lax
,None
,Default
Controls whether a cookie is sent with cross-origin requests, providing some protection against cross-site request forgery attacks.
-
boolean default:
true
Forbids JavaScript from accessing the cookie, for example, through the
Document.cookie
property.
-
boolean
Cookie is only sent to the server when a request is made with the https: scheme (except on localhost), and therefore is more resistant to man-in-the-middle attacks.
-
set of type
string
Must be one of:id
,audience
,subject
,timeout
,idling-timeout
,rolling-timeout
,absolute-timeout
Set of headers to send to upstream, use id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout. E.g.
[ "id", "timeout" ]
will set Session-Id and Session-Timeout request headers.
-
set of type
string
Must be one of:id
,audience
,subject
,timeout
,idling-timeout
,rolling-timeout
,absolute-timeout
Set of headers to send to downstream, use id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout. E.g.
[ "id", "timeout" ]
will set Session-Id and Session-Timeout response headers.
-
string default:
cookie
Must be one of:cookie
,memcache
,memcached
,redis
The session storage for session data: -
cookie
: stores session data with the session cookie (the session cannot be invalidated or revoked without changing session secret, but is stateless, and doesn’t require a database) -memcache
: stores session data in memcached -redis
: stores session data in Redis.
-
boolean default:
false
Configures whether or not session metadata should be stored. This metadata includes information about the active sessions for a specific audience belonging to a specific subject.
-
boolean default:
false
When set to
true
, audiences are forced to share the same subject.
-
boolean default:
false
When set to
true
, the value of subject is hashed before being stored. Only applies whensession_store_metadata
is enabled.
-
boolean default:
false
When set to
true
, the storage key (session ID) is hashed for extra security. Hashing the storage key means it is impossible to decrypt data from the storage without a cookie.
-
string
The memcached session key prefix.
-
string
The memcached unix socket path.
-
string default:
127.0.0.1
The memcached host.
-
integer default:
11211
between:0
65535
The memcached port.
-
record required
-
string default:
127.0.0.1
A string representing a host name, such as example.com.
-
integer default:
6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
string referenceable
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
.
-
string referenceable encrypted
Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
-
string referenceable
Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
-
string referenceable encrypted
Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
-
integer default:
0
Database to use for the Redis connection when using the
redis
strategy
-
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.
-
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
.
-
string
Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
-
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.
-
array of type
record
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.
-
array of type
record
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.
-
boolean default:
false
If set to true, uses SSL to connect to Redis.
-
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.
-
string
A string representing an SNI (server name indication) value for TLS.
-
integer default:
5
Maximum retry attempts for redirection.
-
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.
-
string
The Redis session key prefix.
-
string
The Redis unix socket path.
-
-
boolean default:
false
Specifies whether to always verify tokens stored in the session.
-
string default:
sid
The claim to match against the JWT session cookie.
-
string
The name of the JWT session cookie.
-
array of type
string
default:header, query, body
Must be one of:header
,cookie
,query
,body
Where to look for the bearer token: -
header
: search theAuthorization
,access-token
, andx-access-token
HTTP headers -query
: search the URL’s query string -body
: search the HTTP request body -cookie
: search the HTTP request cookies specified withconfig.bearer_token_cookie_name
.
-
string
The name of the cookie in which the bearer token is passed.
-
array of type
string
default:header, query, body
Must be one of:header
,query
,body
Where to look for the client credentials: -
header
: search the HTTP headers -query
: search the URL’s query string -body
: search from the HTTP request body.
-
array of type
string
default:header, query, body
Must be one of:header
,query
,body
Where to look for the username and password: -
header
: search the HTTP headers -query
: search the URL’s query string -body
: search the HTTP request body.
-
array of type
string
default:header, query, body
Must be one of:header
,query
,body
Where to look for the id token: -
header
: search the HTTP headers -query
: search the URL’s query string -body
: search the HTTP request body.
-
string
The name of the parameter used to pass the id token.
-
array of type
string
default:header, query, body
Must be one of:header
,query
,body
Where to look for the refresh token: -
header
: search the HTTP headers -query
: search the URL’s query string -body
: search the HTTP request body.
-
string
The name of the parameter used to pass the refresh token.
-
boolean default:
true
Specifies whether the plugin should try to refresh (soon to be) expired access tokens if the plugin has a
refresh_token
available.
-
array of type
string
The upstream header claims. Only top level claims are supported.
-
array of type
string
The upstream header names for the claim values.
-
string default:
authorization:bearer
The upstream access token header.
-
string
The upstream access token JWK header.
-
string
The upstream id token header.
-
string
The upstream id token JWK header.
-
string
The upstream refresh token header.
-
string
The upstream user info header.
-
string
The upstream user info JWT header (in case the user info returns a JWT response).
-
string
The upstream introspection header.
-
string
The upstream introspection JWT header.
-
string
The upstream session id header.
-
array of type
string
The downstream header claims. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
The downstream header names for the claim values.
-
string
The downstream access token header.
-
string
The downstream access token JWK header.
-
string
The downstream id token header.
-
string
The downstream id token JWK header.
-
string
The downstream refresh token header.
-
string
The downstream user info header.
-
string
The downstream user info JWT header (in case the user info returns a JWT response).
-
string
The downstream introspection header.
-
string
The downstream introspection JWT header.
-
string
The downstream session id header.
-
array of type
string
default:authorization_code
Must be one of:password
,client_credentials
,authorization_code
,bearer
,introspection
,userinfo
,kong_oauth2
,refresh_token
,session
Enable login functionality with specified grants.
-
string default:
upstream
Must be one of:upstream
,response
,redirect
What to do after successful login: -
upstream
: proxy request to upstream service -response
: terminate request with a response -redirect
: redirect to a different location.
-
array of type
string
default:id_token
Must be one of:id_token
,access_token
,refresh_token
,tokens
,introspection
What tokens to include in
response
body orredirect
query string or fragment: -id_token
: include id token -access_token
: include access token -refresh_token
: include refresh token -tokens
: include the full token endpoint response -introspection
: include introspection response.
-
string default:
fragment
Must be one of:query
,fragment
Where to place
login_tokens
when usingredirect
login_action
: -query
: place tokens in query string -fragment
: place tokens in url fragment (not readable by servers).
-
string
The request query argument that activates the logout.
-
string
The request body argument that activates the logout.
-
string
The request URI suffix that activates the logout.
-
array of type
string
default:POST, DELETE
Must be one of:POST
,GET
,DELETE
The request methods that can activate the logout: -
POST
: HTTP POST method -GET
: HTTP GET method -DELETE
: HTTP DELETE method.
-
boolean default:
false
Revoke tokens as part of the logout.
For more granular token revocation, you can also adjust the
logout_revoke_access_token
andlogout_revoke_refresh_token
parameters.
-
boolean default:
true
Revoke the access token as part of the logout. Requires
logout_revoke
to be set totrue
.
-
boolean default:
true
Revoke the refresh token as part of the logout. Requires
logout_revoke
to be set totrue
.
-
array of type
string
The claim used for consumer mapping. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
array of type
string
default:username, custom_id
Must be one of:id
,username
,custom_id
Consumer fields used for mapping: -
id
: try to find the matching Consumer byid
-username
: try to find the matching Consumer byusername
-custom_id
: try to find the matching Consumer bycustom_id
.
-
boolean default:
false
Do not terminate the request if consumer mapping fails.
-
array of type
string
default:sub
The claim used to derive virtual credentials (e.g. to be consumed by the rate-limiting plugin), in case the consumer mapping is not used. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
string
An optional string (consumer UUID or username) value that functions as an “anonymous” consumer if authentication fails. If empty (default null), requests that fail authentication will return a
4xx
HTTP status code. This value must refer to the consumerid
orusername
attribute, and not itscustom_id
.
-
boolean default:
true
Specifies whether to run this plugin on pre-flight (
OPTIONS
) requests.
-
number default:
0
Defines leeway time (in seconds) for
auth_time
,exp
,iat
, andnbf
claims
-
boolean default:
false
Verify plugin configuration against discovery.
-
boolean default:
true
Verify nonce on authorization code flow.
-
boolean default:
true
Verify tokens for standard claims.
-
boolean default:
true
Verify signature of tokens.
-
array of type
string
Must be one of:password
,client_credentials
,authorization_code
,refresh_token
,session
,introspection
,userinfo
Skip the token signature verification on certain grants: -
password
: OAuth password grant -client_credentials
: OAuth client credentials grant -authorization_code
: authorization code flow -refresh_token
: OAuth refresh token grant -session
: session cookie authentication -introspection
: OAuth introspection -userinfo
: OpenID Connect user info endpoint authentication.
-
boolean default:
false
Enable shared secret, for example, HS256, signatures (when disabled they will not be accepted).
-
array of type
string
Must be one of:password
,client_credentials
,authorization_code
,bearer
,introspection
,userinfo
,kong_oauth2
,refresh_token
,session
Disable issuing the session cookie with the specified grants.
-
number default:
3600
The default cache ttl in seconds that is used in case the cached object does not specify the expiry.
-
number
The maximum cache ttl in seconds (enforced).
-
number
The minimum cache ttl in seconds (enforced).
-
number
The negative cache ttl in seconds.
-
number
The resurrection ttl in seconds.
-
boolean default:
true
Cache the token endpoint requests.
-
string
Salt used for generating the cache key that is used for caching the token endpoint requests.
-
boolean default:
true
Cache the introspection endpoint requests.
-
boolean default:
true
Cache the token exchange endpoint requests.
-
boolean default:
true
Cache the user info requests.
-
boolean default:
false
Specify whether to use the user info endpoint to get additional claims for consumer mapping, credential mapping, authenticated groups, and upstream and downstream headers.
-
boolean default:
false
Remove the credentials used for authentication from the request. If multiple credentials are sent with the same request, the plugin will remove those that were used for successful authentication.
-
number default:
1.1
The HTTP version used for the requests by this plugin: -
1.1
: HTTP 1.1 (the default) -1.0
: HTTP 1.0.
-
string
The HTTP proxy.
-
string referenceable
The HTTP proxy authorization.
-
string
The HTTPS proxy.
-
string referenceable
The HTTPS proxy authorization.
-
string
Do not use proxy with these hosts.
-
boolean default:
true
Use keepalive with the HTTP client.
-
boolean default:
false
Verify identity provider server certificate. If set to
true
, the plugin uses the CA certificate set in thekong.conf
config parameterlua_ssl_trusted_certificate
.
-
number default:
10000
Network IO timeout in milliseconds.
-
boolean default:
false
Display errors on failure responses.
-
boolean default:
false
If
consumer_by
is set tousername
, specify whetherusername
can match consumers case-insensitively.
-
boolean default:
false
Distributed claims are represented by the
_claim_names
and_claim_sources
members of the JSON object containing the claims. If this parameter is set totrue
, the plugin explicitly resolves these distributed claims.
-
boolean default:
true
Specifies whether to expose the error code header, as defined in RFC 6750. If an authorization request fails, this header is sent in the response. Set to
false
to disable.
-
boolean default:
false
Include the scope in the token cache key, so token with different scopes are considered diffrent tokens.
-
string default:
token
Designate token’s parameter name for introspection.
-
string default:
token
Designate token’s parameter name for revocation.
-
string default:
off
Must be one of:off
,strict
,optional
Enable mtls proof of possession. If set to strict, all tokens (from supported auth_methods: bearer, introspection, and session granted with bearer or introspection) are verified, if set to optional, only tokens that contain the certificate hash claim are verified. If the verification fails, the request will be rejected with 401.
-
boolean default:
true
If set to true, only the auth_methods that are compatible with Proof of Possession (PoP) can be configured when PoP is enabled. If set to false, all auth_methods will be configurable and PoP checks will be silently skipped for those auth_methods that are not compatible with PoP.
-
string
ID of the Certificate entity representing the client certificate to use for mTLS client authentication for connections between Kong and the Auth Server.
-
boolean default:
true
Verify identity provider server certificate during mTLS client authentication.
-
string
Alias for the token endpoint to be used for mTLS client authentication. If set it overrides the value in
mtls_endpoint_aliases
returned by the discovery endpoint.
-
string
Alias for the introspection endpoint to be used for mTLS client authentication. If set it overrides the value in
mtls_endpoint_aliases
returned by the discovery endpoint.
-
string
Alias for the introspection endpoint to be used for mTLS client authentication. If set it overrides the value in
mtls_endpoint_aliases
returned by the discovery endpoint.
-
string default:
off
Must be one of:off
,strict
,optional
Enable Demonstrating Proof-of-Possession (DPoP). If set to strict, all request are verified despite the presence of the DPoP key claim (cnf.jkt). If set to optional, only tokens bound with DPoP’s key are verified with the proof.
-
boolean default:
false
Specifies whether to challenge the client with a nonce value for DPoP proof. When enabled it will also be used to calculate the DPoP proof lifetime.
-
number default:
300
Specifies the lifetime in seconds of the DPoP proof. It determines how long the same proof can be used after creation. The creation time is determined by the nonce creation time if a nonce is used, and the iat claim otherwise.
-
array of type
string
If given, these claims are forbidden in the token payload.
-
string default:
off
Must be one of:off
,redis
The strategy to use for the cluster cache. If set, the plugin will share cache with nodes configured with the same strategy backend. Currentlly only introspection cache is shared.
-
record required
-
string default:
127.0.0.1
A string representing a host name, such as example.com.
-
integer default:
6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
integer default:
2000
between:0
2147483646
An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
-
string referenceable
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
.
-
string referenceable encrypted
Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
-
string referenceable
Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won’t be performed. This requires Redis v6.2.0+.
-
string referenceable encrypted
Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
-
integer default:
0
Database to use for the Redis connection when using the
redis
strategy
-
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.
-
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
.
-
string
Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
-
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.
-
array of type
record
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.
-
array of type
record
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.
-
boolean default:
false
If set to true, uses SSL to connect to Redis.
-
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.
-
string
A string representing an SNI (server name indication) value for TLS.
-
integer default:
5
Maximum retry attempts for redirection.
-
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.
-
-
-
number
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
boolean
Deprecation notice: This field is planned to be removed in version 4.0.
-
number
Deprecation notice: This field is planned to be removed in version 4.0.
-
number
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
boolean
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
number
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.
-
boolean
Deprecation notice: This field is planned to be removed in version 4.0.
-
boolean
Deprecation notice: This field is planned to be removed in version 4.0.
-
string
Deprecation notice: This field is planned to be removed in version 4.0.
-
array of type
record
-
integer
Deprecation notice: This field is planned to be removed in version 4.0.