Session Configuration

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 required

  The 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.

• instance_name

  string

  An 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

  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.

• route.name or route.id

  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.

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • secret

    string referenceable encrypted default: beRbEfhfh8hVrEdj5Qmbt4xkUVH2ZCtKf9FPbRQBhLww

    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

    string

    The 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.

    • Strict: The browser sends cookies only if the request originated from the website that set the cookie.
    • Lax: Same-site cookies are withheld on cross-domain subrequests, but are sent when a user navigates to the URL from an external site, for example, by following a link.
    • None or off: Disables the same-site attribute so that a cookie may be sent with cross-site requests. None requires the Secure attribute (cookie_secure) in latest browser versions. For more info, see the SameSite cookies docs on MDN.

  • cookie_http_only

    boolean default: true

    Applies the HttpOnly tag so that the cookie is sent only to a server. See the Restrict access to cookies docs on MDN.

  • 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. See the Restrict access to cookies docs on MDN.

  • 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 type string 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.

    Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout.

    For example: { "id", "timeout" } injects both Session-Id and Session-Timeout in the response headers.

  • request_headers

    set of type string Must be one of: id, audience, subject, timeout, idling-timeout, rolling-timeout, absolute-timeout

    List of information to include, as headers, in the request to the upstream.

    Accepted values are: id, audience, subject, timeout, idling-timeout, rolling-timeout, and absolute-timeout.

    For example, { "id", "timeout" } sets both Session-Id and Session-Timeout in the request headers.

  • logout_methods

    set of type string default: POST, DELETE Must be one of: GET, POST, DELETE

    The methods that may be used to end sessions: POST, DELETE, GET.

  • 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

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_idletime

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_renew

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_discard

  number
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_samesite

  string
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_httponly

  boolean
  Deprecation notice: This field has been deprecated and will be removed in a future version..

• cookie_persistent

  boolean
  Deprecation notice: This field has been deprecated and will be removed in a future version..