Required dependencies: io.ktor:ktor-server-auth
, io.ktor:ktor-server-sessions
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.
You can get general information about authentication and authorization in Ktor in the section.
To enable session
authentication, you need to include the following artifacts in the build script:
-
Add the
ktor-server-sessions
dependency for using sessions: -
Add the
ktor-server-auth
dependency for authentication:
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.
To install the session
authentication provider, call the session function with the required session type inside the install
block:
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.sessions.*
//...
install(Authentication) {
session<UserSession> {
// 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.
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.
{src="snippets/auth-form-session/src/main/kotlin/com/example/Application.kt" include-lines="11"}
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.
{src="snippets/auth-form-session/src/main/kotlin/com/example/Application.kt" include-lines="14-19"}
You can learn more about configuring sessions from .
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.
{src="snippets/auth-form-session/src/main/kotlin/com/example/Application.kt" include-lines="20,32-44"}
To save information about a logged-in user to a session, use the call.sessions.set function.
{src="snippets/auth-form-session/src/main/kotlin/com/example/Application.kt" include-lines="67-73"}
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.
{src="snippets/auth-form-session/src/main/kotlin/com/example/Application.kt" include-lines="75-81"}
You can find the full example here: auth-form-session.