Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Session Configuration

By Kong Inc.
You are browsing unreleased documentation.

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: lt9BJW1n5RfhCxTbNIKqsj8THW7YNdXTA0VW6KQwBUwg

      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.

    • string default: session

      The name of the cookie.

    • string default: /

      The resource in the host where the cookie is available.

    • string

      The domain with which the cookie is intended to be exchanged.

    • string default: Strict Must be one of: Strict, Lax, None, Default

      Determines whether and how a cookie may be sent with cross-site requests.

    • boolean default: true

      Applies the HttpOnly tag so that the cookie is sent only to a server.

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

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

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