このページは、まだ日本語ではご利用いただけません。翻訳中です。
構成
このプラグインはDBレスモードに対応しています。
互換性のあるプロトコル
OpenID Connectプラグインは以下のプロトコルに対応しています:
grpc
, grpcs
, http
, https
パラメータ
このプラグインの設定で使用できるすべてのパラメータのリストは次のとおりです。
-
name or plugin
string requiredプラグイン名。この場合は
openid-connect
。- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
name
です。 - Kubernetes で KongPlugin オブジェクトを使用する場合、フィールドは
plugin
です。
- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
-
instance_name
stringプラグインのインスタンスを識別するための任意のカスタム名 (例:
openid-connect_my-service
。インスタンス名はKong ManagerとKonnectに表示されるので、 例えば複数のサービスで同じプラグインを複数のコンテキストで実行する場合に便利です。また、Kong Admin API経由で特定のプラグインインスタンスに アクセスするためにも使用できます。
インスタンス名は、次のコンテキスト内で一意である必要があります。
- Kong Gateway Enterpriseのワークスペース内
- Konnectのコントロールプレーン(CP)またはコントロールプレーン(CP)グループ内
- Kong Gateway (OSS)の全世界
-
service.name or service.id
stringプラグインが対象とするサービス名または ID。最上位の
/plugins
エンドポイント. からプラグインをサービスに追加する場合は、これらのパラメータのいずれかを設定してください/services/{serviceName|Id}/plugins
を使用する場合は必要ありません。 -
route.name or route.id
stringプラグインがターゲットとするルート名または ID。最上位の
/plugins
エンドポイント. を通るルートにプラグインを追加する場合は、これらのパラメータのいずれかを設定してください/routes/{routeName|Id}/plugins
を使用する場合は必要ありません。 -
enabled
boolean default:true
このプラグインが適用されるかどうか。
-
config
record required-
issuer
string requiredThe discovery endpoint (or the issuer identifier). When there is no discovery endpoint, please also configure
config.using_pseudo_issuer=true
.
-
using_pseudo_issuer
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
.
-
discovery_headers_names
array of typestring
Extra header names passed to the discovery endpoint.
-
discovery_headers_values
array of typestring
Extra header values passed to the discovery endpoint.
-
extra_jwks_uris
set of typestring
JWKS URIs whose public keys are trusted (in addition to the keys found with the discovery).
-
rediscovery_lifetime
number default:30
Specifies how long (in seconds) the plugin waits between discovery attempts. Discovery is still triggered on an as-needed basis.
-
auth_methods
array of typestring
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.
-
client_id
array of typestring
referenceable encryptedThe client id(s) that the plugin uses when it calls authenticated endpoints on the identity provider.
-
client_secret
array of typestring
referenceable encryptedThe client secret.
-
client_auth
array of typestring
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).
-
client_jwk
array of typerecord
The JWK used for the private_key_jwt authentication.
-
issuer
string
-
kty
string
-
use
string
-
key_ops
array of typestring
-
alg
string
-
kid
string
-
x5u
string
-
x5c
array of typestring
-
x5t
string
-
x5t#S256
string
-
k
string referenceable encrypted
-
x
string
-
y
string
-
crv
string
-
n
string
-
e
string
-
d
string referenceable encrypted
-
p
string referenceable encrypted
-
q
string referenceable encrypted
-
dp
string referenceable encrypted
-
dq
string referenceable encrypted
-
qi
string referenceable encrypted
-
oth
string referenceable encrypted
-
r
string referenceable encrypted
-
t
string referenceable encrypted
-
-
client_alg
array of typestring
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.
-
client_arg
string default:client_id
The client to use for this request (the selection is made with a request parameter with the same name).
-
redirect_uri
array of typestring
The redirect URI passed to the authorization and token endpoints.
-
login_redirect_uri
array of typestring
referenceableWhere to redirect the client when
login_action
is set toredirect
.
-
logout_redirect_uri
array of typestring
referenceableWhere to redirect the client after the logout.
-
forbidden_redirect_uri
array of typestring
Where to redirect the client on forbidden requests.
-
forbidden_error_message
string default:Forbidden
The error message for the forbidden requests (when not using the redirection).
-
forbidden_destroy_session
boolean default:true
Destroy any active session for the forbidden requests.
-
unauthorized_destroy_session
boolean default:true
Destroy any active session for the unauthorized requests.
-
unauthorized_redirect_uri
array of typestring
Where to redirect the client on unauthorized requests.
-
unauthorized_error_message
string default:Unauthorized
The error message for the unauthorized requests (when not using the redirection).
-
unexpected_redirect_uri
array of typestring
Where to redirect the client when unexpected errors happen with the requests.
-
response_mode
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.
-
response_type
array of typestring
default:code
The response type passed to the authorization endpoint.
-
scopes
array of typestring
referenceable default:openid
The scopes passed to the authorization and token endpoints.
-
audience
array of typestring
The audience passed to the authorization endpoint.
-
issuers_allowed
array of typestring
The issuers allowed to be present in the tokens (
iss
claim).
-
scopes_required
array of typestring
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.
-
scopes_claim
array of typestring
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.
-
audience_required
array of typestring
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.
-
audience_claim
array of typestring
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.
-
groups_required
array of typestring
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.
-
groups_claim
array of typestring
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.
-
roles_required
array of typestring
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.
-
roles_claim
array of typestring
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.
-
domains
array of typestring
The allowed values for the
hd
claim.
-
max_age
numberThe maximum age (in seconds) compared to the
auth_time
claim.
-
authenticated_groups_claim
array of typestring
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.
-
pushed_authorization_request_endpoint
stringThe pushed authorization endpoint. If set it overrides the value in
pushed_authorization_request_endpoint
returned by the discovery endpoint.
-
pushed_authorization_request_endpoint_auth_method
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
-
require_pushed_authorization_requests
booleanForcibly 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
).
-
require_proof_key_for_code_exchange
booleanForcibly 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).
-
require_signed_request_object
booleanForcibly 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).
-
authorization_endpoint
stringThe authorization endpoint. If set it overrides the value in
authorization_endpoint
returned by the discovery endpoint.
-
authorization_query_args_names
array of typestring
Extra query argument names passed to the authorization endpoint.
-
authorization_query_args_values
array of typestring
Extra query argument values passed to the authorization endpoint.
-
authorization_query_args_client
array of typestring
Extra query arguments passed from the client to the authorization endpoint.
-
authorization_rolling_timeout
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.
-
authorization_cookie_name
string default:authorization
The authorization cookie name.
-
authorization_cookie_path
string default:/
starts_with:/
The authorization cookie Path flag.
-
authorization_cookie_domain
stringThe authorization cookie Domain flag.
-
authorization_cookie_same_site
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.
-
authorization_cookie_http_only
boolean default:true
Forbids JavaScript from accessing the cookie, for example, through the
Document.cookie
property.
-
authorization_cookie_secure
booleanCookie 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.
-
preserve_query_args
boolean default:false
With this parameter, you can preserve request query arguments even when doing authorization code flow.
-
token_endpoint
stringThe token endpoint. If set it overrides the value in
token_endpoint
returned by the discovery endpoint.
-
token_endpoint_auth_method
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
-
token_headers_names
array of typestring
Extra header names passed to the token endpoint.
-
token_headers_values
array of typestring
Extra header values passed to the token endpoint.
-
token_headers_client
array of typestring
Extra headers passed from the client to the token endpoint.
-
token_headers_replay
array of typestring
The names of token endpoint response headers to forward to the downstream client.
-
token_headers_prefix
stringAdd a prefix to the token endpoint response headers before forwarding them to the downstream client.
-
token_headers_grants
array of typestring
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.
-
token_post_args_names
array of typestring
Extra post argument names passed to the token endpoint.
-
token_post_args_values
array of typestring
Extra post argument values passed to the token endpoint.
-
token_post_args_client
array of typestring
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.
-
introspection_endpoint
stringThe introspection endpoint. If set it overrides the value in
introspection_endpoint
returned by the discovery endpoint.
-
introspection_endpoint_auth_method
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
-
introspection_hint
string default:access_token
Introspection hint parameter value passed to the introspection endpoint.
-
introspection_check_active
boolean default:true
Check that the introspection response has an
active
claim with a value oftrue
.
-
introspection_accept
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).
-
introspection_headers_names
array of typestring
Extra header names passed to the introspection endpoint.
-
introspection_headers_values
array of typestring
referenceable encryptedExtra header values passed to the introspection endpoint.
-
introspection_headers_client
array of typestring
Extra headers passed from the client to the introspection endpoint.
-
introspection_post_args_names
array of typestring
Extra post argument names passed to the introspection endpoint.
-
introspection_post_args_values
array of typestring
Extra post argument values passed to the introspection endpoint.
-
introspection_post_args_client
array of typestring
Extra post arguments passed from the client to the introspection endpoint.
-
introspect_jwt_tokens
boolean default:false
Specifies whether to introspect the JWT access tokens (can be used to check for revocations).
-
revocation_endpoint
stringThe revocation endpoint. If set it overrides the value in
revocation_endpoint
returned by the discovery endpoint.
-
revocation_endpoint_auth_method
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
-
end_session_endpoint
stringThe end session endpoint. If set it overrides the value in
end_session_endpoint
returned by the discovery endpoint.
-
userinfo_endpoint
stringThe user info endpoint. If set it overrides the value in
userinfo_endpoint
returned by the discovery endpoint.
-
userinfo_accept
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).
-
userinfo_headers_names
array of typestring
Extra header names passed to the user info endpoint.
-
userinfo_headers_values
array of typestring
Extra header values passed to the user info endpoint.
-
userinfo_headers_client
array of typestring
Extra headers passed from the client to the user info endpoint.
-
userinfo_query_args_names
array of typestring
Extra query argument names passed to the user info endpoint.
-
userinfo_query_args_values
array of typestring
Extra query argument values passed to the user info endpoint.
-
userinfo_query_args_client
array of typestring
Extra query arguments passed from the client to the user info endpoint.
-
token_exchange_endpoint
stringThe token exchange endpoint.
-
session_secret
string referenceable encryptedThe session secret.
-
session_audience
string default:default
The session audience, which is the intended target application. For example
"my-application"
.
-
session_cookie_name
string default:session
The session cookie name.
-
session_remember
boolean default:false
Enables or disables persistent sessions.
-
session_remember_cookie_name
string default:remember
Persistent session cookie name. Use with the
remember
configuration parameter.
-
session_remember_rolling_timeout
number default:604800
Specifies how long the persistent session is considered valid in seconds. 0 disables the checks and rolling.
-
session_remember_absolute_timeout
number default:2592000
Limits how long the persistent session can be renewed in seconds, until re-authentication is required. 0 disables the checks.
-
session_idling_timeout
number default:900
Specifies how long the session can be inactive until it is considered invalid in seconds. 0 disables the checks and touching.
-
session_rolling_timeout
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.
-
session_absolute_timeout
number default:86400
Limits how long the session can be renewed in seconds, until re-authentication is required. 0 disables the checks.
-
session_cookie_path
string default:/
starts_with:/
The session cookie Path flag.
-
session_cookie_domain
stringThe session cookie Domain flag.
-
session_cookie_same_site
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.
-
session_cookie_http_only
boolean default:true
Forbids JavaScript from accessing the cookie, for example, through the
Document.cookie
property.
-
session_cookie_secure
booleanCookie 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.
-
session_request_headers
set of typestring
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.
-
session_response_headers
set of typestring
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.
-
session_storage
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.
-
session_store_metadata
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.
-
session_enforce_same_subject
boolean default:false
When set to
true
, audiences are forced to share the same subject.
-
session_hash_subject
boolean default:false
When set to
true
, the value of subject is hashed before being stored. Only applies whensession_store_metadata
is enabled.
-
session_hash_storage_key
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.
-
session_memcached_prefix
stringThe memcached session key prefix.
-
session_memcached_socket
stringThe memcached unix socket path.
-
session_memcached_host
string default:127.0.0.1
The memcached host.
-
session_memcached_port
integer default:11211
between:0
65535
The memcached port.
-
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.
-
prefix
stringThe Redis session key prefix.
-
socket
stringThe Redis unix socket path.
-
-
reverify
boolean default:false
Specifies whether to always verify tokens stored in the session.
-
jwt_session_claim
string default:sid
The claim to match against the JWT session cookie.
-
jwt_session_cookie
stringThe name of the JWT session cookie.
-
bearer_token_param_type
array of typestring
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
.
-
bearer_token_cookie_name
stringThe name of the cookie in which the bearer token is passed.
-
client_credentials_param_type
array of typestring
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.
-
password_param_type
array of typestring
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.
-
id_token_param_type
array of typestring
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.
-
id_token_param_name
stringThe name of the parameter used to pass the id token.
-
refresh_token_param_type
array of typestring
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.
-
refresh_token_param_name
stringThe name of the parameter used to pass the refresh token.
-
refresh_tokens
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.
-
upstream_headers_claims
array of typestring
The upstream header claims. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
upstream_headers_names
array of typestring
The upstream header names for the claim values.
-
upstream_access_token_header
string default:authorization:bearer
The upstream access token header.
-
upstream_access_token_jwk_header
stringThe upstream access token JWK header.
-
upstream_id_token_header
stringThe upstream id token header.
-
upstream_id_token_jwk_header
stringThe upstream id token JWK header.
-
upstream_refresh_token_header
stringThe upstream refresh token header.
-
upstream_user_info_header
stringThe upstream user info header.
-
upstream_user_info_jwt_header
stringThe upstream user info JWT header (in case the user info returns a JWT response).
-
upstream_introspection_header
stringThe upstream introspection header.
-
upstream_introspection_jwt_header
stringThe upstream introspection JWT header.
-
upstream_session_id_header
stringThe upstream session id header.
-
downstream_headers_claims
array of typestring
The downstream header claims. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
downstream_headers_names
array of typestring
The downstream header names for the claim values.
-
downstream_access_token_header
stringThe downstream access token header.
-
downstream_access_token_jwk_header
stringThe downstream access token JWK header.
-
downstream_id_token_header
stringThe downstream id token header.
-
downstream_id_token_jwk_header
stringThe downstream id token JWK header.
-
downstream_refresh_token_header
stringThe downstream refresh token header.
-
downstream_user_info_header
stringThe downstream user info header.
-
downstream_user_info_jwt_header
stringThe downstream user info JWT header (in case the user info returns a JWT response).
-
downstream_introspection_header
stringThe downstream introspection header.
-
downstream_introspection_jwt_header
stringThe downstream introspection JWT header.
-
downstream_session_id_header
stringThe downstream session id header.
-
login_methods
array of typestring
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.
-
login_action
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.
-
login_tokens
array of typestring
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.
-
login_redirect_mode
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).
-
logout_query_arg
stringThe request query argument that activates the logout.
-
logout_post_arg
stringThe request body argument that activates the logout.
-
logout_uri_suffix
stringThe request URI suffix that activates the logout.
-
logout_methods
array of typestring
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.
-
logout_revoke
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.
-
logout_revoke_access_token
boolean default:true
Revoke the access token as part of the logout. Requires
logout_revoke
to be set totrue
.
-
logout_revoke_refresh_token
boolean default:true
Revoke the refresh token as part of the logout. Requires
logout_revoke
to be set totrue
.
-
consumer_claim
array of typestring
The claim used for consumer mapping. If multiple values are set, it means the claim is inside a nested object of the token payload.
-
consumer_by
array of typestring
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
.
-
consumer_optional
boolean default:false
Do not terminate the request if consumer mapping fails.
-
credential_claim
array of typestring
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.
-
anonymous
stringAn 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
.
-
run_on_preflight
boolean default:true
Specifies whether to run this plugin on pre-flight (
OPTIONS
) requests.
-
leeway
number default:0
Defines leeway time (in seconds) for
auth_time
,exp
,iat
, andnbf
claims
-
verify_parameters
boolean default:false
Verify plugin configuration against discovery.
-
verify_nonce
boolean default:true
Verify nonce on authorization code flow.
-
verify_claims
boolean default:true
Verify tokens for standard claims.
-
verify_signature
boolean default:true
Verify signature of tokens.
-
ignore_signature
array of typestring
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.
-
enable_hs_signatures
boolean default:false
Enable shared secret, for example, HS256, signatures (when disabled they will not be accepted).
-
disable_session
array of typestring
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.
-
cache_ttl
number default:3600
The default cache ttl in seconds that is used in case the cached object does not specify the expiry.
-
cache_ttl_max
numberThe maximum cache ttl in seconds (enforced).
-
cache_ttl_min
numberThe minimum cache ttl in seconds (enforced).
-
cache_ttl_neg
numberThe negative cache ttl in seconds.
-
cache_ttl_resurrect
numberThe resurrection ttl in seconds.
-
cache_tokens
boolean default:true
Cache the token endpoint requests.
-
cache_tokens_salt
stringSalt used for generating the cache key that is used for caching the token endpoint requests.
-
cache_introspection
boolean default:true
Cache the introspection endpoint requests.
-
cache_token_exchange
boolean default:true
Cache the token exchange endpoint requests.
-
cache_user_info
boolean default:true
Cache the user info requests.
-
search_user_info
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.
-
hide_credentials
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.
-
http_version
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.
-
http_proxy
stringThe HTTP proxy.
-
http_proxy_authorization
stringThe HTTP proxy authorization.
-
https_proxy
stringThe HTTPS proxy.
-
https_proxy_authorization
stringThe HTTPS proxy authorization.
-
no_proxy
stringDo not use proxy with these hosts.
-
keepalive
boolean default:true
Use keepalive with the HTTP client.
-
ssl_verify
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
.
-
timeout
number default:10000
Network IO timeout in milliseconds.
-
display_errors
boolean default:false
Display errors on failure responses.
-
by_username_ignore_case
boolean default:false
If
consumer_by
is set tousername
, specify whetherusername
can match consumers case-insensitively.
-
resolve_distributed_claims
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.
-
expose_error_code
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.
-
token_cache_key_include_scope
boolean default:false
Include the scope in the token cache key, so token with different scopes are considered diffrent tokens.
-
introspection_token_param_name
string default:token
Designate token’s parameter name for introspection.
-
revocation_token_param_name
string default:token
Designate token’s parameter name for revocation.
-
proof_of_possession_mtls
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.
-
proof_of_possession_auth_methods_validation
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.
-
tls_client_auth_cert_id
stringID of the Certificate entity representing the client certificate to use for mTLS client authentication for connections between Kong and the Auth Server.
-
tls_client_auth_ssl_verify
boolean default:true
Verify identity provider server certificate during mTLS client authentication.
-
mtls_token_endpoint
stringAlias 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.
-
mtls_introspection_endpoint
stringAlias 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.
-
mtls_revocation_endpoint
stringAlias 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.
-
proof_of_possession_dpop
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.
-
dpop_use_nonce
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.
-
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.
-
claims_forbidden
array of typestring
If given, these claims are forbidden in the token payload.
-
cluster_cache_strategy
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.
-
cluster_cache_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.
-
-
-
authorization_cookie_lifetime
numberDeprecation notice: This field is planned to be removed in version 4.0.
-
authorization_cookie_samesite
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
authorization_cookie_httponly
booleanDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_lifetime
numberDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_idletime
numberDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_samesite
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_httponly
booleanDeprecation notice: This field is planned to be removed in version 4.0.
-
session_memcache_prefix
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_memcache_socket
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_memcache_host
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_memcache_port
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_renew
numberDeprecation notice: This field is planned to be removed in version 4.0.
-
session_cookie_maxsize
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_strategy
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_compressor
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_prefix
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_socket
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_host
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_port
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_username
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_password
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_connect_timeout
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_read_timeout
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_send_timeout
integerDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_ssl
booleanDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_ssl_verify
booleanDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_server_name
stringDeprecation notice: This field is planned to be removed in version 4.0.
-
session_redis_cluster_nodes
array of typerecord
Deprecation notice: This field is planned to be removed in version 4.0.
-
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.
-
-
session_redis_cluster_max_redirections
integerDeprecation notice: This field is planned to be removed in version 4.0.