Session Configuration

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

  string required

  The name of the plugin, in this case session.

• instance_name

  string

  An optional custom name to identify an instance of the plugin, for example session_my-service. Useful when running the same plugin in multiple contexts, for example, on multiple services.

• 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/SERVICE_NAME|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/ROUTE_NAME|ID/plugins.

• enabled

  boolean default: true

  Whether this plugin will be applied.

• config

  record required
  • secret

    string referenceable encrypted default: KMMFrVmbW8X1AW0JLXrJMpGnBe4tNc3ESBmsKKe7e5Ia

    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.

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

  • 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 response to the downstream.

  • read_body_for_logout

    boolean default: false

  • logout_methods

    set of type string 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.

Deprecated parameters

Important: The following fields have been deprecated and will be removed in a future version.
See the changelog for this plugin for new field mapping info.

• cookie_lifetime

  number

• cookie_idletime

  number

• cookie_renew

  number

• cookie_discard

  number

• cookie_samesite

  string

• cookie_httponly

  boolean

• cookie_persistent

  boolean