Class session
Session library provides HTTP session management capabilities for OpenResty based applications, libraries and proxies.
Functions
session_instance:open () | Opens session
This can be used to open a session. |
Tables
session.configuration | Session configuration options |
Methods
session:init ([configuration]) | Initializes session library |
session:new ([configuration]) | Creates new session |
session:open ([configuration]) | Opens session
This can be used to open a session. |
session:start ([configuration]) | Starts the session and refreshes it as needed
This can be used to start a session. |
session:logout ([configuration]) | Logouts session
It logouts from a specific audience. |
session:destroy ([configuration]) | Destroys session |
Functions
Methods- session_instance:open ()
-
Opens session
This can be used to open a session. It will either return an existing session or a new session.
Returns:
- true or nil session instance
- string information why session could not be opened
Tables
- session.configuration
-
Session configuration options
Fields:
- secret
Secret used for the key derivation. The secret is hashed with SHA-256 before using it. E.g.
"RaJKp8UQW1"
. - secret_fallbacks
Array of secrets that can be used as alternative secrets (when doing key rotation), E.g.
{ "6RfrAYYzYq", "MkbTkkyF9C" }
. - ikm
Initial key material (or ikm) can be specified directly (without using a secret) with exactly 32 bytes of data, e.g.
"5ixIW4QVMk0dPtoIhn41Eh1I9enP2060"
- ikm_fallbacks
Array of initial key materials that can be used as alternative keys (when doing key rotation), E.g.
{ "QvPtlPKxOKdP5MCu1oI3lOEXIVuDckp7" }
. - cookie_prefix
Cookie prefix, use
nil
,"__Host-"
or"__Secure-"
(defaults tonil
) - cookie_name
Session cookie name, e.g.
"session"
(defaults to"session"
) - cookie_path
Cookie path, e.g.
"/"
(defaults to"/"
) - cookie_domain
Cookie domain, e.g.
"example.com"
(defaults tonil
) - cookie_http_only
Mark cookie HTTP only, use
true
orfalse
(defaults totrue
) - cookie_secure
Mark cookie secure, use
nil
,true
orfalse
(defaults tonil
) - cookie_priority
Cookie priority, use
nil
,"Low"
,"Medium"
, or"High"
(defaults tonil
) - cookie_same_site
Cookie same-site policy, use
nil
,"Lax"
,"Strict"
, or"None"
(defaults to"Lax"
) - cookie_same_party
Mark cookie with same party flag, use
nil
,true
, orfalse
(default:nil
) - cookie_partitioned
Mark cookie with partitioned flag, use
nil
,true
, orfalse
(default:nil
) - remember
Enable or disable persistent sessions, use
nil
,true
, orfalse
(defaults tofalse
) - remember_cookie_name
Persistent session cookie name, e.g.
"remember"
(defaults to"remember"
) - audience
Session audience, e.g.
"my-application"
(defaults to"default"
) - subject
Session subject, e.g.
"john.doe@example.com"
(defaults tonil
) - stale_ttl
When session is saved a new session is created, stale ttl specifies how long the old one can still be used, e.g.
10
(defaults to10
) (in seconds) - idling_timeout
Idling timeout specifies how long the session can be inactive until it is considered invalid, e.g.
900
(defaults to900
, or 15 minutes) (in seconds) - rolling_timeout
Rolling timeout specifies how long the session can be used until it needs to be renewed, e.g.
3600
(defaults to3600
, or an hour) (in seconds) - absolute_timeout
Absolute timeout limits how long the session can be renewed, until re-authentication is required, e.g.
86400
(defaults to86400
, or a day) (in seconds) - remember_timeout
Remember timeout specifies how long the persistent session is considered valid, e.g.
604800
(defaults to604800
, or a week) (in seconds) - storage
Storage is responsible of storing session data, use
nil
(data is stored in cookie),dshm
,file
,memcached
,mysql
,postgres
,redis
,redis-cluster
,redis-sentinel
, orshm
, or give a name of custom module ("custom.session.storage"
), or a table that implements session storage interface (defaults tonil
) - dshm
Configuration for dshm storage, e.g.
{ prefix = "sessions" }
- file
Configuration for file storage, e.g.
{ path = "/tmp", suffix = "session" }
- memcached
Configuration for memcached storage, e.g.
{ prefix = "sessions" }
- mysql
Configuration for MySQL / MariaDB storage, e.g.
{ database = "sessions" }
- postgres
Configuration for Postgres storage, e.g.
{ database = "sessions" }
- redis
Configuration for Redis / Redis Sentinel / Redis Cluster storages, e.g.
{ prefix = "sessions" }
- shm
Configuration for shared memory storage, e.g.
{ zone = "sessions" }
- secret
Secret used for the key derivation. The secret is hashed with SHA-256 before using it. E.g.
Methods
- session:init ([configuration])
-
Initializes session library This function can be called on init or
init_worker
phases on OpenResty to set global default configuration to all session instances created by this library.Parameters:
- configuration table session configuration overrides (optional)
Usage:
require "resty.session".init({ audience = "my-application", })
- session:new ([configuration])
-
Creates new session This creates a new session instance.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
table
session instance
Usage:
local session = require "resty.session".new() -- OR local session = require "resty.session".new({ audience = "my-application", })
- session:open ([configuration])
-
Opens session
This can be used to open a session. It will either return an existing session or a new session.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
- table session instance
- string information why session could not be opened
-
boolean
true
, if session existed, otherwisefalse
Usage:
local session = require "resty.session".open() -- OR local session, err, exists = require "resty.session".open({ audience = "my-application", })
- session:start ([configuration])
-
Starts the session and refreshes it as needed
This can be used to start a session. It will either return an existing session or a new session. In case there is an existing session, the session will be refreshed as well (as needed).
Parameters:
- configuration table session configuration overrides (optional)
Returns:
- table session instance
- string information why session could not be logged out
-
boolean
true
, if session existed, otherwisefalse
-
boolean
true
, if session was refreshed, otherwisefalse
Usage:
local session = require "resty.session".start() -- OR local session, err, exists, refreshed = require "resty.session".start() audience = "my-application", })
- session:logout ([configuration])
-
Logouts session
It logouts from a specific audience.
A single session cookie may be shared between multiple audiences (or applications), thus there is a need to be able to logout from just a single audience while keeping the session for the other audiences.
When there is only a single audience, then this can be considered equal to session.destroy.
When the last audience is logged out, the cookie will be destroyed as well and invalidated on a client.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
boolean
true
session exists for an audience and was logged out successfully, otherwisefalse
- string information why the session could not be logged out
-
boolean
true
if session existed, otherwisefalse
-
boolean
true
if session was logged out, otherwisefalse
Usage:
require "resty.session".logout() -- OR local ok, err, exists, logged_out = require "resty.session".logout({ audience = "my-application", })
- session:destroy ([configuration])
-
Destroys session It destroys the whole session and clears the cookies.
Parameters:
- configuration table session configuration overrides (optional)
Returns:
-
boolean
true
session exists and was destroyed successfully, otherwisenil
- string information why session could not be destroyed
-
boolean
true
if session existed, otherwisefalse
-
boolean
true
if session was destroyed, otherwisefalse
Usage:
require "resty.session".destroy() -- OR local ok, err, exists = require "resty.session".destroy({ cookie_name = "auth", })