セッション
必要な依存関係: io.ktor:ktor-server-sessions
コード例: session-cookie-client, session-cookie-server, session-header-server
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
Sessions プラグインは、異なる HTTP リクエスト間でデータを永続化するメカニズムを提供します。典型的なユースケースとしては、ログインしたユーザーの ID の保存、ショッピングカートの内容、またはクライアント上でのユーザー設定の保持などが挙げられます。Ktor では、Cookie またはカスタムヘッダーを使用してセッションを実装したり、セッションデータをサーバー側に保存するかクライアントへ渡すかを選択したり、セッションデータの署名や暗号化などを行うことができます。
このトピックでは、Sessions プラグインのインストール方法、設定方法、およびルートハンドラー内でのセッションデータへのアクセス方法について説明します。
依存関係の追加
セッションのサポートを有効にするには、ビルドスクリプトに ktor-server-sessions アーティファクトを含める必要があります。
implementation(ktorLibs.server.sessions)implementation ktorLibs.server.sessions<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-sessions-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>Sessions のインストール
Sessions プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、Sessions をインストールする方法を示しています。
embeddedServer()関数の呼び出し内。Applicationクラスに明示的に定義されたmodule()拡張関数内。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sessions.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Sessions)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.sessions.*
// ...
fun Application.module() {
install(Sessions)
// ...
}Sessions プラグインは、特定のルートにインストールすることもできます。 これは、アプリケーションの異なるリソースに対して異なる Sessions 設定が必要な場合に役立ちます。
セッション設定の概要
Sessions プラグインを設定するには、以下の手順を実行する必要があります。
サーバーとクライアント間でのデータ受け渡し方法の選択: Cookie またはカスタムヘッダーのいずれを使用するか選択します。Cookie はプレーンな HTML アプリケーションに適しており、カスタムヘッダーは API 向けです。
セッションペイロードの保存場所の選択: クライアント側かサーバー側かを選択します。シリアライズされたセッションデータを Cookie/ヘッダー値としてクライアントに渡すか、ペイロードをサーバーに保存してセッション識別子のみを渡すことができます。
セッションペイロードをサーバーに保存する場合は、保存方法の選択が可能です。サーバーメモリ内またはフォルダー内に保存できます。また、セッションデータを保持するためのカスタムストレージを実装することもできます。
セッションデータの保護: クライアントに渡される機密性の高いセッションデータを保護するために、セッションのペイロードに署名および暗号化を行う必要があります。
Sessions を設定した後は、ルートハンドラー内でセッションデータの取得および設定が行えます。
データクラスの作成
セッションを設定する前に、セッションデータを保存するためのデータクラスを作成する必要があります。 例えば、以下の UserSession クラスは、セッション ID とページビュー数を保存するために使用されます。
@Serializable
data class UserSession(val id: String, val count: Int)複数のセッションを使用する場合は、複数のデータクラスを作成する必要があります。
セッションデータの受け渡し: Cookie vs ヘッダー
Cookie
Cookie を使用してセッションデータを渡すには、install(Sessions) ブロック内で指定された名前とデータクラスを指定して cookie 関数を呼び出します。
install(Sessions) {
cookie<UserSession>("user_session")
}上記の例では、セッションデータは Set-Cookie ヘッダーに追加された user_session 属性を使用してクライアントに渡されます。cookie ブロック内で渡すことにより、他の Cookie 属性を設定できます。例えば、以下のコードスニペットは Cookie のパスと有効期限を指定する方法を示しています。
install(Sessions) {
cookie<UserSession>("user_session") {
cookie.path = "/"
cookie.maxAgeInSeconds = 10
}
}必要な属性が明示的に公開されていない場合は、extensions プロパティを使用します。例えば、SameSite 属性は以下のように渡すことができます。
install(Sessions) {
cookie<UserSession>("user_session") {
cookie.extensions["SameSite"] = "lax"
}
}利用可能な設定項目についての詳細は、CookieConfiguration を参照してください。
アプリケーションを本番環境にデプロイする前に、secure プロパティが true に設定されていることを確認してください。これにより、安全な接続(SSL)経由でのみ Cookie が転送されるようになり、HTTPS ダウングレード攻撃からセッションデータを保護できます。
ヘッダー
カスタムヘッダーを使用してセッションデータを渡すには、install(Sessions) ブロック内で指定された名前とデータクラスを指定して header 関数を呼び出します。
install(Sessions) {
header<CartSession>("cart_session")
}上記の例では、セッションデータは cart_session カスタムヘッダーを使用してクライアントに渡されます。 クライアント側では、セッションデータを取得するために各リクエストにこのヘッダーを追加する必要があります。
CORS プラグインを使用してクロスオリジンリクエストを処理する場合は、次のように CORS 設定にカスタムヘッダーを追加してください。
install(CORS) {
allowHeader("cart_session")
exposeHeader("cart_session")
}変更時のみセッションデータを送信
デフォルトでは、Ktor は変更されていない場合でも、すべてのレスポンスでセッションデータを送信します。
セッションデータが変更された場合にのみ送信するには、セッション設定で sendOnlyIfModified フラグを有効にします。
install(Sessions) {
cookie<MySession>("SESSION") {
sendOnlyIfModified = true
}
}このオプションは、Cookie とヘッダーベースのどちらのセッションでも利用できます。
セッションペイロードの保存場所: クライアント vs サーバー
Ktor では、セッションデータを2つの方法で管理できます。
クライアントとサーバー間でセッションデータをやり取りする。
Cookie またはヘッダー関数にセッション名のみを渡した場合、セッションデータはクライアントとサーバー間でやり取りされます。この場合、クライアントに渡される機密性の高いセッションデータを保護するために、セッションのペイロードに署名と暗号化を行う必要があります。
サーバー上にセッションデータを保存し、クライアントとサーバー間ではセッション ID のみをやり取りする。
この場合、サーバー上のペイロードの保存場所を選択できます。例えば、メモリ内や指定されたフォルダー内にセッションデータを保存したり、独自のカスタムストレージを実装したりできます。
サーバー上にセッションペイロードを保存
Ktor では、セッションデータをサーバー上に保存し、サーバーとクライアント間ではセッション ID のみをやり取りすることができます。この場合、サーバー上のどこにペイロードを保持するかを選択できます。
インメモリストレージ
SessionStorageMemory を使用すると、セッションの内容をメモリに保存できます。このストレージはサーバーの実行中にデータを保持し、サーバーが停止すると情報は破棄されます。例えば、以下のようにして Cookie をサーバーメモリに保存できます。
cookie<CartSession>("cart_session", SessionStorageMemory()) {
}完全なサンプルはこちらで確認できます: session-cookie-server。
SessionStorageMemory は開発用途のみを想定していることに注意してください。
ディレクトリストレージ
directorySessionStorage を使用すると、指定したディレクトリ下のファイルにセッションデータを保存できます。例えば、build/.sessions ディレクトリ配下のファイルにセッションデータを保存するには、次のように directorySessionStorage を作成します。
header<CartSession>("cart_session", directorySessionStorage(File("build/.sessions"))) {
}完全なサンプルはこちらで確認できます: session-header-server。
カスタムストレージ
Ktor は、カスタムストレージを実装できる SessionStorage インターフェースを提供しています。
interface SessionStorage {
suspend fun invalidate(id: String)
suspend fun write(id: String, value: String)
suspend fun read(id: String): String
}3つの関数はすべてサスペンド関数です。SessionStorageMemory を参考にすることができます。
セッションデータの保護
セッションデータの署名
セッションデータに署名すると、セッション内容の改ざんを防ぐことができますが、ユーザーがその内容を閲覧することは可能です。 セッションに署名するには、署名キーを SessionTransportTransformerMessageAuthentication コンストラクターに渡し、そのインスタンスを transform 関数に渡します。
install(Sessions) {
val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
cookie<CartSession>("cart_session", SessionStorageMemory()) {
cookie.path = "/"
transform(SessionTransportTransformerMessageAuthentication(secretSignKey))
}
}SessionTransportTransformerMessageAuthentication はデフォルトの認証アルゴリズムとして HmacSHA256 を使用しますが、これは変更可能です。
セッションデータの署名と暗号化
セッションデータを署名および暗号化すると、セッション内容の読み取りと改ざんの両方を防ぐことができます。 セッションの署名と暗号化を行うには、署名/暗号化キーを SessionTransportTransformerEncrypt コンストラクターに渡し、そのインスタンスを transform 関数に渡します。
install(Sessions) {
val secretEncryptKey = "00112233445566778899aabbccddeeff".hexToByteArray()
val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
cookie<UserSession>("user_session") {
cookie.path = "/"
cookie.maxAgeInSeconds = 10
transform(SessionTransportTransformerEncrypt(secretEncryptKey, secretSignKey))
}
}Ktor バージョン 3.0.0 で暗号化方式がアップデートされたことに注意してください。以前のバージョンから移行する場合は、既存のセッションとの互換性を確保するために、SessionTransportTransformerEncrypt のコンストラクターで backwardCompatibleRead プロパティを使用してください。
デフォルトでは、SessionTransportTransformerEncrypt は AES および HmacSHA256 アルゴリズムを使用しますが、これらは変更可能です。
セッション内容の取得と設定
特定のルートに対してセッション内容を設定するには、call.sessions プロパティを使用します。set メソッドを使用すると、新しいセッションインスタンスを作成できます。
get("/login") {
call.sessions.set(UserSession(id = "123abc", count = 0))
call.respondRedirect("/user")
}セッション内容を取得するには、登録されているセッション型のいずれかを型パラメーターとして受け取る get を呼び出します。
get("/user") {
val userSession = call.sessions.get<UserSession>()
if (userSession != null) {
}セッションを変更する(例えばカウンターをインクリメントする)には、データクラスの copy メソッドを呼び出す必要があります。
get("/user") {
val userSession = call.sessions.get<UserSession>()
if (userSession != null) {
call.sessions.set(userSession.copy(count = userSession.count + 1))
call.respondText("Session ID is ${userSession.id}. Reload count is ${userSession.count}.")
} else {
call.respondText("Session doesn't exist or is expired.")
}
}何らかの理由でセッションをクリアする必要がある場合(例えばユーザーがログアウトしたときなど)は、clear 関数を呼び出します。
get("/logout") {
call.sessions.clear<UserSession>()
call.respondRedirect("/user")
}完全なサンプルはこちらで確認できます: session-cookie-client。
セッションの遅延取得
デフォルトでは、Ktor はルートが実際にセッションを必要としているかどうかにかかわらず、セッションを含むすべてのリクエストに対してストレージからセッションを読み込もうとします。この動作は、特にカスタムセッションストレージを使用しているアプリケーションにおいて、不要なオーバーヘッドを引き起こす可能性があります。
io.ktor.server.sessions.deferred システムプロパティを有効にすることで、セッションの読み込みを遅延させることができます。
System.setProperty("io.ktor.server.sessions.deferred", "true")サンプル
以下の実行可能なサンプルでは、Sessions プラグインの使用方法を示しています。
- session-cookie-client: Cookie を使用して、署名および暗号化されたセッションペイロードをクライアントに渡す方法を示しています。
- session-cookie-server: セッションペイロードをサーバーメモリに保持し、署名されたセッション ID を Cookie を使用してクライアントに渡す方法を示しています。
- session-header-server: サーバー上のディレクトリストレージにセッションペイロードを保持し、カスタムヘッダーを使用して署名されたセッション ID をクライアントに渡す方法を示しています。
