Session

Overview Examples Configuration reference Changelog

How the Session plugin works

The Session plugin can be configured globally or with an entity (for example, a Gateway Service or a Route) and is always used in conjunction with another Kong Gateway authentication plugin. This plugin is intended to work similarly to the multiple authentication setup.

When the Session plugin is enabled in conjunction with an authentication plugin, it runs before credential verification. If no session is found, then the authentication plugin runs again and credentials are checked normally. If the credential verification is successful, then the Session plugin creates a new session to use for subsequent requests.

When a new request comes in and a session is already present, then the Session plugin attaches the ngx.ctx variables to let the authentication plugin know that authentication has already occurred via session validation. As this configuration is a logical OR scenario and you likely want to forbid anonymous access, you should configure the Request Termination plugin on an anonymous Consumer. If not configured, unauthorized requests will be allowed through. For more information, see multiple authentication and learn how to prevent unauthorized access in a multi-auth scenario.

Default Session plugin settings

By default, the Session plugin favors security using a Secure, HTTPOnly, and Samesite=Strict cookie. config.cookie_domain is automatically set using the Nginx variable host, but can be overridden.

Session data storage

The session data can be stored in the cookie itself (encrypted) by setting config.storage to cookie, or inside Kong Gateway by setting storage to kong. The session data stores these context variables:

ngx.ctx.authenticated_consumer.id
ngx.ctx.authenticated_credential.id
ngx.ctx.authenticated_groups

The plugin also sets a ngx.ctx.authenticated_session for communication between the access and header_filter phases in the plugin.

Authenticated groups

Authenticated groups from other authentication plugins are stored in ngx.ctx.authenticated_groups. The Session plugin will store authenticated groups in the data of the current session. Since the Session plugin runs before authentication plugins, it also sets associated authenticated_groups headers.

Kong Gateway storage adapter

When storage is set to kong, the Session plugin extends the functionality of lua-resty-session with its own session data storage adapter. This stores encrypted session data into the current database strategy, and the cookie doesn’t contain any session data.

Data stored in the database is encrypted, and the cookie contains only the session ID, expiration time, and HMAC signature. Sessions use the built-in Kong Gateway DAO ttl mechanism that destroys sessions after the specified rolling_timeout unless renewal occurs during normal browser activity. You can log out of the application via a XHR request (or something similar) to manually handle the redirects.

Logging out

It is typical to provide users the ability to log out (as in, to manually destroy) their current session. Logging out is possible with either query parameters or POST parameters in the request URL. The config.logout_methods allows the plugin to limit logging out based on the HTTP verb. When config.logout_query_arg is set, it checks the presence of the URL query parameter specified. Likewise, when config.logout_post_arg is set, it checks for the presence of the specified variable in the request body.

When there’s a session present and the incoming request is a logout request, the Session plugin returns a 200 before continuing in the plugin run loop, and the request doesn’t continue to the upstream.

Kong Manager

To enable sessions authentication, configure the following parameters in kong.conf:

enforce_rbac = on
admin_gui_auth = $AUTH_PLUGIN
admin_gui_session_conf = {
    "secret":"$SET_SECRET",
    "cookie_name":"$SET_COOKIE_NAME",
    "storage":"$SET_STORAGE",
    "rolling_timeout":$NUMBER_OF_SECONDS_UNTIL_RENEWAL,
    "cookie_secure":$SET_DEPENDING_ON_PROTOCOL,
    "cookie_same_site":"$SET_DEPENDING_ON_DOMAIN",
    "store_metadata": true
}

Attribute	Description
`cookie_name`	A name for the cookie. For example, `"cookie_name":"kong_cookie"`
`secret`	The secret used in keyed HMAC generation. Although the Session plugin’s default is a random string, the `secret` must be manually set for use with Kong Manager since it must be the same across all Kong workers/nodes.
`storage`	The location where session data is stored. The default value is `cookie`. It may be more secure if set to `kong`, since access to the database would be required.
`cookie_lifetime`	The duration (in seconds) that the session will remain open. The default value is `3600`.
`cookie_secure`	Applies the Secure directive so that the cookie may be sent to the server only with an encrypted request over the HTTPS protocol. See Session security overview for exceptions. The default value is `true`.
`cookie_same_site`	Determines whether and how a cookie may be sent with cross-site requests. See Session security overview for exceptions. The default value is `strict`.
`hash_subject`	Whether to hash or not the subject when `store_metadata` is enabled. The default value is `false`.
`store_metadata`	Whether to also store metadata of sessions, such as collecting data of sessions for a specific audience belonging to a specific subject. The default value is `false`. Upon enabling this option, also set `storage` to `kong`.

For more information on configuring Kong Manager see the Kong Manager reference documentation

Session security overview

Kong Gateway uses secure defaults for session management, including:

Secure and HttpOnly cookie flags to prevent client-side access and require HTTPS
SameSite directive to mitigate cross-site request forgery (CSRF) risks

However, certain settings must be adjusted depending on your environment:

Use "cookie_secure": false when testing over HTTP (not recommended for production)
If the Admin API and Kong Manager run on separate domains, use "cookie_same_site": "Lax"

When using "storage": "cookie", logging out only deletes the session client-side. To fully invalidate sessions server-side, use "storage": "kong".

Session configuration notes

Kong Gateway supports a variety of session behaviors based on how you configure admin_gui_session_conf:

Use storage = "kong" to store session data server-side and support logout invalidation.
Set cookie_secure = false only in testing environments without HTTPS.
Use store_metadata = true to support session invalidation on password change.
Set hash_subject = true alongside store_metadata = true to avoid storing raw session subjects (for PII reasons).

These options allow fine-tuning of security, privacy, and logout behavior depending on your deployment model.

Known limitations

Due to limitations of OpenResty, the header_filter phase can’t connect to the database. This poses a problem for initial retrieval of a cookie (fresh session). There is a small window of time where the cookie is sent to client, but the database insert hasn’t been committed yet because the database call is in a ngx.timer thread.

The workaround for this issue is to wait for some interval of time (~100-500ms) after Set-Cookie header is sent to the client before making subsequent requests. This is not a problem during session renewal period, as renewal happens in the access phase.