Sessions
The Sessions plugin provides a mechanism to persist data between different HTTP requests. Typical use cases include storing a logged-in user's ID, the contents of a shopping basket, or keeping user preferences on the client. In Ktor, you can implement sessions by using cookies or custom headers, choose whether to store session data on the server or pass it to the client, sign and encrypt session data and more.
In this topic, we'll look at how to install the Sessions
plugin, configure it, and access session data inside route handlers.
Add dependencies
To enable support for sessions, you need to include the ktor-server-sessions
artifact in the build script:
Install Sessions
To install the Sessions
plugin to the application, pass it to the install
function in the specified module. The code snippets below show how to install Sessions
...
... inside the
embeddedServer
function call.... inside the explicitly defined
module
, which is an extension function of theApplication
class.
The Sessions
plugin can also be installed to specific routes. This might be useful if you need different Sessions
configurations for different application resources.
Session configuration overview
To configure the Sessions
plugin, you need to perform the following steps:
Create a data class: before configuring a session, you need to create a data class for storing session data.
Choose how to pass data between the server and client: using cookies or a custom header. Cookies suit better for plain HTML applications, while custom headers are intended for APIs.
Choose where to store the session payload: on the client or server. You can pass the serialized session's data to the client using a cookie/header value or store the payload on the server and pass only a session identifier.
If you want to store the session payload on the server, you can choose how to store it: in the server memory or in a folder. You can also implement a custom storage for keeping session data.
Protect session data: to protect sensitive session data passed to the client, you need to sign and encrypt the session's payload.
After configuring Sessions
, you can get and set session data inside route handlers.
Create a data class
Before configuring a session, you need to create a data class for storing session data. For example, the UserSession
class below will be used to store the session ID and the number of page views:
You need to create several data classes if you are going to use several sessions.
Pass session data: Cookie vs Header
Cookie
To pass session data using cookies, call the cookie
function with the specified name and data class inside the install(Sessions)
block:
In the example above, session data will be passed to the client using the user_session
attribute added to the Set-Cookie
header. You can configure other cookie attributes by passing them inside the cookie
block. For example, the code snippet below shows how to specify a cookie's path and expiration time:
If the required attribute is not exposed explicitly, use the extensions
property. For example, you can pass the SameSite
attribute in the following way:
To learn more about available configurations settings, see CookieConfiguration.
Header
To pass session data using a custom header, call the header
function with the specified name and data class inside the install(Sessions)
block:
In the example above, session data will be passed to the client using the cart_session
custom header. On the client side, you need to append this header to each request to get session data.
Store session payload: Client vs Server
In Ktor, you can manage the session data in two ways:
Pass session data between the client and server.
If you pass only the session name to the cookie or header function, session data will be passed between the client and server. In this case, you need to sign and encrypt the session's payload to protect sensitive session data passed to the client.
Store session data on the server and pass only a session ID between the client and server.
In such a case, you can choose where to store the payload on the server. For example, you can store session data in memory, in a specified folder, or you can implement your own custom storage.
Store session payload on server
Ktor allows you to store session data on the server and pass only a session ID between the server and the client. In this case, you can choose where to keep the payload on the server.
In-memory storage
SessionStorageMemory enables storing a session's content in memory. This storage keeps data while the server is running and discards information once the server stops. For example, you can store cookies in the server memory as follows:
You can find the full example here: session-cookie-server.
Directory storage
directorySessionStorage can be used to store a session's data in a file under the specified directory. For example, to store session data in a file under the build/.sessions
directory, create the directorySessionStorage
in this way:
You can find the full example here: session-header-server.
Custom storage
Ktor provides the SessionStorage interface that allows you to implement a custom storage.
All three functions are suspending. You can use SessionStorageMemory as a reference.
Protect session data
Sign session data
Signing session data prevents modifying a session's content but allows users to see this content. To sign a session, pass a sign key to the SessionTransportTransformerMessageAuthentication
constructor and pass this instance to the transform
function:
SessionTransportTransformerMessageAuthentication
uses HmacSHA256
as the default authentication algorithm, which can be changed.
Sign and encrypt session data
Signing and encrypting session data prevents reading and modifying a session's content. To sign and encrypt a session, pass a sign/encrypt keys to the SessionTransportTransformerEncrypt
constructor and pass this instance to the transform
function:
By default, SessionTransportTransformerEncrypt
uses the AES
and HmacSHA256
algorithms, which can be changed.
Get and set session content
To set the session content for a specific route, use the call.sessions
property. The set
method allows you to create a new session instance:
To get the session content, you can call get
receiving one of the registered session types as type parameter:
To modify a session, for example, to increment a counter, you need to call the copy
method of the data class:
When you need to clear a session for any reason (for example, when a user logs out), call the clear
function:
You can find the full example here: session-cookie-client.
Examples
The runnable examples below demonstrate how to use the Sessions
plugin:
session-cookie-client shows how to pass signed and encrypted session payload to the client using cookies.
session-cookie-server shows how to keep session payload in a server memory and pass a signed session ID to the client using cookies.
session-header-server shows how to keep session payload on a server in a directory storage and pass signed session ID to the client using a custom header.