Session authentication
Sessions provide 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, a user that already has an associated session can be authenticated using the session
provider. For example, when a user logs in using a web form for the first time, you can save a username to a cookie session and authorize this user on subsequent requests using the session
provider.
Add dependencies
To enable session
authentication, you need to include the following artifacts in the build script:
Add the
ktor-server-sessions
dependency for using sessions:implementation("io.ktor:ktor-server-sessions:$ktor_version")implementation "io.ktor:ktor-server-sessions:$ktor_version"<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-sessions-jvm</artifactId> <version>${ktor_version}</version> </dependency>Add the
ktor-server-auth
dependency for authentication:implementation("io.ktor:ktor-server-auth:$ktor_version")implementation "io.ktor:ktor-server-auth:$ktor_version"<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-auth-jvm</artifactId> <version>${ktor_version}</version> </dependency>
Session authentication flow
The authentication flow with sessions might vary and depends on how users are authenticated in your application. Let's see how it might look with the form-based authentication:
A client makes a request containing web form data (which includes the username and password) to a server.
A server validates credentials sent by a client, saves a username to a cookie session, and responds with the requested content and a cookie containing a username.
A client makes a subsequent request with a cookie to the protected resource.
Based on received cookie data, Ktor checks that a cookie session exists for this user and, optionally, performs additional validations on received session data. In a case of successful validation, a server responds with the requested content.
Install session authentication
To install the session
authentication provider, call the session function with the required session type inside the install
block:
Configure session authentication
This section demonstrates how to authenticate a user with a form-based authentication, save information about this user to a cookie session, and then authorize this user on subsequent requests using the session
provider. You can find the complete example here: auth-form-session.
Step 1: Create a data class
First, you need to create a data class for storing session data. Note that this class should inherit Principal since the validate function should return a Principal
in the case of successful authentication.
Step 2: Install and configure a session
After creating a data class, you need to install and configure the Sessions
plugin. A code snippet below shows how to install and configure a cookie session with the specified cookie path and expiration time.
You can learn more about configuring sessions from Session configuration overview.
Step 3: Configure session authentication
The session
authentication provider exposes its settings via the SessionAuthenticationProvider.Config class. In the example below, the following settings are specified:
The
validate
function checks the session instance and returnsPrincipal
in the case of successful authentication.The
challenge
function specifies an action performed if authentication fails. For instance, you can redirect back to a login page or send UnauthorizedResponse.
Step 4: Save user data in a session
To save information about a logged-in user to a session, use the call.sessions.set function.
Step 5: Protect specific resources
After configuring the session
provider, you can protect specific resources in our application using the authenticate function. In the case of successful authentication, you can retrieve an authenticated Principal
(the UserSession instance) inside a route handler using the call.principal
function and information about a user.
You can find the full example here: auth-form-session.