Skip to content
Server Plugin

セッション

必要な依存関係: 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 アーティファクトを含める必要があります。

kotlin
implementation(ktorLibs.server.sessions)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
groovy
implementation ktorLibs.server.sessions
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-sessions-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

Sessions のインストール ​

Sessions プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、Sessions をインストールする方法を示しています。

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.sessions.*
// ...
fun Application.module() {
    install(Sessions)
    // ...
}

Sessions プラグインは、特定のルートにインストールすることもできます。 これは、アプリケーションの異なるリソースに対して異なる Sessions 設定が必要な場合に役立ちます。

セッション設定の概要 ​

Sessions プラグインを設定するには、以下の手順を実行する必要があります。

  1. データクラスの作成: セッションを設定する前に、セッションデータを保存するためのデータクラスを作成する必要があります。

  2. サーバーとクライアント間でのデータ受け渡し方法の選択: Cookie またはカスタムヘッダーのいずれを使用するか選択します。Cookie はプレーンな HTML アプリケーションに適しており、カスタムヘッダーは API 向けです。

  3. セッションペイロードの保存場所の選択: クライアント側かサーバー側かを選択します。シリアライズされたセッションデータを Cookie/ヘッダー値としてクライアントに渡すか、ペイロードをサーバーに保存してセッション識別子のみを渡すことができます。

    セッションペイロードをサーバーに保存する場合は、保存方法の選択が可能です。サーバーメモリ内またはフォルダー内に保存できます。また、セッションデータを保持するためのカスタムストレージを実装することもできます。

  4. セッションデータの保護: クライアントに渡される機密性の高いセッションデータを保護するために、セッションのペイロードに署名および暗号化を行う必要があります。

Sessions を設定した後は、ルートハンドラー内でセッションデータの取得および設定が行えます。

データクラスの作成 ​

セッションを設定する前に、セッションデータを保存するためのデータクラスを作成する必要があります。 例えば、以下の UserSession クラスは、セッション ID とページビュー数を保存するために使用されます。

kotlin
@Serializable
data class UserSession(val id: String, val count: Int)

複数のセッションを使用する場合は、複数のデータクラスを作成する必要があります。

Cookie を使用してセッションデータを渡すには、install(Sessions) ブロック内で指定された名前とデータクラスを指定して cookie 関数を呼び出します。

kotlin
install(Sessions) {
    cookie<UserSession>("user_session")
}

上記の例では、セッションデータは Set-Cookie ヘッダーに追加された user_session 属性を使用してクライアントに渡されます。cookie ブロック内で渡すことにより、他の Cookie 属性を設定できます。例えば、以下のコードスニペットは Cookie のパスと有効期限を指定する方法を示しています。

kotlin
install(Sessions) {
    cookie<UserSession>("user_session") {
        cookie.path = "/"
        cookie.maxAgeInSeconds = 10
    }
}

必要な属性が明示的に公開されていない場合は、extensions プロパティを使用します。例えば、SameSite 属性は以下のように渡すことができます。

kotlin
install(Sessions) {
    cookie<UserSession>("user_session") {
        cookie.extensions["SameSite"] = "lax"
    }
}

利用可能な設定項目についての詳細は、CookieConfiguration を参照してください。

アプリケーションを本番環境にデプロイする前に、secure プロパティが true に設定されていることを確認してください。これにより、安全な接続(SSL)経由でのみ Cookie が転送されるようになり、HTTPS ダウングレード攻撃からセッションデータを保護できます。

カスタムヘッダーを使用してセッションデータを渡すには、install(Sessions) ブロック内で指定された名前とデータクラスを指定して header 関数を呼び出します。

kotlin
install(Sessions) {
    header<CartSession>("cart_session")
}

上記の例では、セッションデータは cart_session カスタムヘッダーを使用してクライアントに渡されます。 クライアント側では、セッションデータを取得するために各リクエストにこのヘッダーを追加する必要があります。

CORS プラグインを使用してクロスオリジンリクエストを処理する場合は、次のように CORS 設定にカスタムヘッダーを追加してください。

kotlin
install(CORS) {
    allowHeader("cart_session")
    exposeHeader("cart_session")
}

変更時のみセッションデータを送信 ​

デフォルトでは、Ktor は変更されていない場合でも、すべてのレスポンスでセッションデータを送信します。

セッションデータが変更された場合にのみ送信するには、セッション設定で sendOnlyIfModified フラグを有効にします。

kotlin
install(Sessions) {
    cookie<MySession>("SESSION") {
        sendOnlyIfModified = true
    }
}

このオプションは、Cookie とヘッダーベースのどちらのセッションでも利用できます。

セッションペイロードの保存場所: クライアント vs サーバー ​

Ktor では、セッションデータを2つの方法で管理できます。

  • クライアントとサーバー間でセッションデータをやり取りする。

    Cookie またはヘッダー関数にセッション名のみを渡した場合、セッションデータはクライアントとサーバー間でやり取りされます。この場合、クライアントに渡される機密性の高いセッションデータを保護するために、セッションのペイロードに署名と暗号化を行う必要があります。

  • サーバー上にセッションデータを保存し、クライアントとサーバー間ではセッション ID のみをやり取りする。

    この場合、サーバー上のペイロードの保存場所を選択できます。例えば、メモリ内や指定されたフォルダー内にセッションデータを保存したり、独自のカスタムストレージを実装したりできます。

サーバー上にセッションペイロードを保存 ​

Ktor では、セッションデータをサーバー上に保存し、サーバーとクライアント間ではセッション ID のみをやり取りすることができます。この場合、サーバー上のどこにペイロードを保持するかを選択できます。

インメモリストレージ ​

SessionStorageMemory を使用すると、セッションの内容をメモリに保存できます。このストレージはサーバーの実行中にデータを保持し、サーバーが停止すると情報は破棄されます。例えば、以下のようにして Cookie をサーバーメモリに保存できます。

kotlin
cookie<CartSession>("cart_session", SessionStorageMemory()) {
}

完全なサンプルはこちらで確認できます: session-cookie-server。

SessionStorageMemory は開発用途のみを想定していることに注意してください。

ディレクトリストレージ ​

directorySessionStorage を使用すると、指定したディレクトリ下のファイルにセッションデータを保存できます。例えば、build/.sessions ディレクトリ配下のファイルにセッションデータを保存するには、次のように directorySessionStorage を作成します。

kotlin
header<CartSession>("cart_session", directorySessionStorage(File("build/.sessions"))) {
}

完全なサンプルはこちらで確認できます: session-header-server。

カスタムストレージ ​

Ktor は、カスタムストレージを実装できる SessionStorage インターフェースを提供しています。

kotlin
interface SessionStorage {
    suspend fun invalidate(id: String)
    suspend fun write(id: String, value: String)
    suspend fun read(id: String): String
}

3つの関数はすべてサスペンド関数です。SessionStorageMemory を参考にすることができます。

セッションデータの保護 ​

セッションデータの署名 ​

セッションデータに署名すると、セッション内容の改ざんを防ぐことができますが、ユーザーがその内容を閲覧することは可能です。 セッションに署名するには、署名キーを SessionTransportTransformerMessageAuthentication コンストラクターに渡し、そのインスタンスを transform 関数に渡します。

kotlin
install(Sessions) {
    val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
    cookie<CartSession>("cart_session", SessionStorageMemory()) {
        cookie.path = "/"
        transform(SessionTransportTransformerMessageAuthentication(secretSignKey))
    }
}

SessionTransportTransformerMessageAuthentication はデフォルトの認証アルゴリズムとして HmacSHA256 を使用しますが、これは変更可能です。

セッションデータの署名と暗号化 ​

セッションデータを署名および暗号化すると、セッション内容の読み取りと改ざんの両方を防ぐことができます。 セッションの署名と暗号化を行うには、署名/暗号化キーを SessionTransportTransformerEncrypt コンストラクターに渡し、そのインスタンスを transform 関数に渡します。

kotlin
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 メソッドを使用すると、新しいセッションインスタンスを作成できます。

kotlin
get("/login") {
    call.sessions.set(UserSession(id = "123abc", count = 0))
    call.respondRedirect("/user")
}

セッション内容を取得するには、登録されているセッション型のいずれかを型パラメーターとして受け取る get を呼び出します。

kotlin
get("/user") {
    val userSession = call.sessions.get<UserSession>()
    if (userSession != null) {
}

セッションを変更する(例えばカウンターをインクリメントする)には、データクラスの copy メソッドを呼び出す必要があります。

kotlin
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 関数を呼び出します。

kotlin
get("/logout") {
    call.sessions.clear<UserSession>()
    call.respondRedirect("/user")
}

完全なサンプルはこちらで確認できます: session-cookie-client。

セッションの遅延取得 ​

デフォルトでは、Ktor はルートが実際にセッションを必要としているかどうかにかかわらず、セッションを含むすべてのリクエストに対してストレージからセッションを読み込もうとします。この動作は、特にカスタムセッションストレージを使用しているアプリケーションにおいて、不要なオーバーヘッドを引き起こす可能性があります。

io.ktor.server.sessions.deferred システムプロパティを有効にすることで、セッションの読み込みを遅延させることができます。

kotlin
System.setProperty("io.ktor.server.sessions.deferred", "true")

サンプル ​

以下の実行可能なサンプルでは、Sessions プラグインの使用方法を示しています。