You are browsing documentation for an outdated plugin version.
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
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
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
,none
The authentication method used by the client (plugin) when calling the endpoint.
-
array of type
record
-
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
-
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
The response mode passed to the authorization endpoint: -
query
: Instructs the identity provider to pass parameters in query string -form_post
: Instructs the identity provider to pass parameters in request body -fragment
: Instructs the identity provider to pass parameters in uri fragment (rarely useful as the plugin itself cannot read it)
-
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.
-
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.
-
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.
-
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.
-
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.
-
string
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
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:/
A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).
-
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
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,none
The token endpoint authentication method: -
client_secret_basic
: sendclient_id
andclient_secret
inAuthorization: Basic
header -client_secret_post
: sendclient_id
andclient_secret
as part of the body -client_secret_jwt
: send client assertion signed with theclient_secret
as part of the body -private_key_jwt
: send client assertion signed with theprivate key
as part of the body -none
: 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
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,none
The introspection endpoint authentication method: -
client_secret_basic
: sendclient_id
andclient_secret
inAuthorization: Basic
header -client_secret_post
: sendclient_id
andclient_secret
as part of the body -client_secret_jwt
: send client assertion signed with theclient_secret
as part of the body -private_key_jwt
: send client assertion signed with theprivate key
as part of the body -none
: 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.
-
boolean default:
false
Specifies whether to introspect the JWT access tokens (can be used to check for revocations).
-
string
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string Must be one of:
client_secret_basic
,client_secret_post
,client_secret_jwt
,private_key_jwt
,none
The revocation endpoint authentication method: -
client_secret_basic
: sendclient_id
andclient_secret
inAuthorization: Basic
header -client_secret_post
: sendclient_id
andclient_secret
as part of the body -client_secret_jwt
: send client assertion signed with theclient_secret
as part of the body -private_key_jwt
: send client assertion signed with theprivate key
as part of the body -none
: do not authenticate
-
string
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
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
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
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:/
A string representing a URL path, such as /path/to/resource. Must start with a forward slash (/) and must not contain empty segments (i.e., two consecutive forward slashes).
-
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 type
string
Must be one of:id
,audience
,subject
,timeout
,idling-timeout
,rolling-timeout
,absolute-timeout
-
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
An integer representing a port number between 0 and 65535, inclusive.
-
string
The Redis session key prefix.
-
string
The Redis unix socket path.
-
string default:
127.0.0.1
The Redis host
-
integer default:
6379
between:0
65535
An integer representing a port number between 0 and 65535, inclusive.
-
string referenceable
Username to use for Redis connection when the
redis
session storage is defined and ACL authentication is desired. If undefined, ACL authentication will not be performed. This requires Redis v6.0.0+. The username cannot be set todefault
.
-
string referenceable encrypted
Password to use for Redis connection when the
redis
session storage is defined. If undefined, no AUTH commands are sent to Redis.
-
integer
Session redis connection timeout in milliseconds.
-
integer
Session redis read timeout in milliseconds.
-
integer
Session redis send timeout in milliseconds.
-
boolean default:
false
Use SSL/TLS for Redis connection.
-
boolean default:
false
Verify identity provider server certificate.
-
string
The SNI used for connecting the Redis server.
-
array of type
record
The Redis cluster node host. Takes an array of host records, with either
ip
orhost
, andport
values.
-
integer
The Redis cluster maximum redirects.
-
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 the 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.
-
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
-
string
The upstream session id header.
-
array of type
string
The downstream header claims.
-
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
-
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.
-
boolean default:
true
Revoke the access token as part of the logout.
-
boolean default:
true
Revoke the refresh token as part of the logout.
-
array of type
string
The claim used for consumer mapping.
-
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.
-
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
Allow some leeway (in seconds) on the iat claim and ttl / expiry verification.
-
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
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string
The HTTP proxy authorization.
-
string
A string representing a URL, such as https://example.com/path/to/resource?q=search.
-
string
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.
-
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.
-
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.
-
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.
-
-
number
Deprecation notice:
-
string
Deprecation notice:
-
boolean
Deprecation notice:
-
number
Deprecation notice:
-
number
Deprecation notice:
-
string
Deprecation notice:
-
boolean
Deprecation notice:
-
string
Deprecation notice:
-
string
Deprecation notice:
-
string
Deprecation notice:
-
integer
Deprecation notice:
-
integer
Deprecation notice:
-
number
Deprecation notice:
-
integer
Deprecation notice:
-
string
Deprecation notice:
-
string
Deprecation notice: