You are browsing documentation for an outdated plugin version.
Configuration
This plugin is partially compatible with DB-less mode.
config.storage
must be set to cookie
. The kong
strategy uses
a database, and is not supported. The plugin currently lacks checks
for this invalid configuration in DB-less mode.
Compatible protocols
The Session plugin is compatible with the following protocols:
grpc
, grpcs
, http
, https
, tcp
, tls
, tls_passthrough
, udp
, ws
, wss
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
-
name or plugin
string requiredThe name of the plugin, in this case
session
.- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
name
. - If using the KongPlugin object in Kubernetes, the field is
plugin
.
- If using the Kong Admin API, Konnect API, declarative configuration, or decK files, the field is
-
instance_name
stringAn optional custom name to identify an instance of the plugin, for example
session_my-service
.The instance name shows up in Kong Manager and in Konnect, so it's useful when running the same plugin in multiple contexts, for example, on multiple services. You can also use it to access a specific plugin instance via the Kong Admin API.
An instance name must be unique within the following context:
- Within a workspace for Kong Gateway Enterprise
- Within a control plane or control plane group for Konnect
- Globally for Kong Gateway (OSS)
-
service.name or service.id
stringThe name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level
/plugins
endpoint. Not required if using/services/{serviceName|Id}/plugins
. -
route.name or route.id
stringThe name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level
/plugins
endpoint. Not required if using/routes/{routeName|Id}/plugins
. -
enabled
boolean default:true
Whether this plugin will be applied.
-
config
record required-
secret
string referenceable encrypted default:rvGfd6EK2RJZmJKuGpYQFuExLl10Qe6069Nvih04wT8o
The secret that is used in keyed HMAC generation.
-
storage
string default:cookie
Must be one of:cookie
,kong
Determines where the session data is stored.
kong
: Stores encrypted session data into Kong’s current database strategy; the cookie will not contain any session data.cookie
: Stores encrypted session data within the cookie itself.
-
audience
string default:default
The session audience, which is the intended target application. For example
"my-application"
.
-
idling_timeout
number default:900
The session cookie idle time, in seconds.
-
rolling_timeout
number default:3600
The session cookie rolling timeout, in seconds. Specifies how long the session can be used until it needs to be renewed.
-
absolute_timeout
number default:86400
The session cookie absolute timeout, in seconds. Specifies how long the session can be used until it is no longer valid.
-
stale_ttl
number default:10
The duration, in seconds, after which an old cookie is discarded, starting from the moment when the session becomes outdated and is replaced by a new one.
-
cookie_name
string default:session
The name of the cookie.
-
cookie_path
string default:/
The resource in the host where the cookie is available.
-
cookie_domain
stringThe domain with which the cookie is intended to be exchanged.
-
cookie_same_site
string default:Strict
Must be one of:Strict
,Lax
,None
,Default
Determines whether and how a cookie may be sent with cross-site requests.
-
cookie_http_only
boolean default:true
Applies the
HttpOnly
tag so that the cookie is sent only to a server.
-
cookie_secure
boolean default:true
Applies the Secure directive so that the cookie may be sent to the server only with an encrypted request over the HTTPS protocol.
-
remember
boolean default:false
Enables or disables persistent sessions.
-
remember_cookie_name
string default:remember
Persistent session cookie name. Use with the
remember
configuration parameter.
-
remember_rolling_timeout
number default:604800
The persistent session rolling timeout window, in seconds.
-
remember_absolute_timeout
number default:2592000
The persistent session absolute timeout limit, in seconds.
-
response_headers
set of typestring
Must be one of:id
,audience
,subject
,timeout
,idling-timeout
,rolling-timeout
,absolute-timeout
List of information to include, as headers, in the response to the downstream.
-
request_headers
set of typestring
Must be one of:id
,audience
,subject
,timeout
,idling-timeout
,rolling-timeout
,absolute-timeout
List of information to include, as headers, in the response to the downstream.
-
read_body_for_logout
boolean default:false
-
logout_methods
set of typestring
default:POST, DELETE
Must be one of:GET
,POST
,DELETE
A set of HTTP methods that the plugin will respond to.
-
logout_query_arg
string default:session_logout
The query argument passed to logout requests.
-
logout_post_arg
string default:session_logout
The POST argument passed to logout requests. Do not change this property.
-
-
cookie_lifetime
numberDeprecation notice:
-
cookie_idletime
numberDeprecation notice:
-
cookie_renew
numberDeprecation notice:
-
cookie_discard
numberDeprecation notice:
-
cookie_samesite
stringDeprecation notice:
-
cookie_httponly
booleanDeprecation notice:
-
cookie_persistent
booleanDeprecation notice: