Skip to content

Ktor Server 中的工作階段驗證 ​

必要相依性: io.ktor:ktor-server-auth, io.ktor:ktor-server-sessions

程式碼範例: auth-form-session

Native 伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援: ✖️

工作階段 (Session) 提供了一種在不同 HTTP 請求之間保留資料的機制。常見的使用案例包括儲存已登入使用者的 ID、購物籃的內容,或在用戶端保留使用者偏好設定。

在 Ktor 中,已具有關聯工作階段的使用者可以使用 session 提供者進行驗證。例如,當使用者第一次使用 Web 表單登入時,您可以將使用者名稱儲存到 Cookie 工作階段中,並在後續請求中使用 session 提供者對此使用者進行授權。

您可以在 Ktor Server 中的驗證與授權章節中取得關於 Ktor 驗證與授權的一般資訊。

Ktor 還提供了一種型別安全的工作階段驗證配置。它為路由處理常式提供非 null 的 principal 以及對已儲存工作階段的讀寫存取權限,並將工作階段型別與 principal 型別分開。請參閱 型別安全的工作階段驗證。

新增相依性 ​

若要啟用 session 驗證,您需要在建置指令碼中包含以下構件:

  • 新增用於使用工作階段的 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>
  • 新增用於驗證的 ktor-server-auth 相依性:

    kotlin
    implementation(ktorLibs.server.auth)
    上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
    groovy
    implementation ktorLibs.server.auth
    上述程式碼片段使用 Ktor 版本目錄來指定 Ktor 相依性。
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-auth-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>

工作階段驗證流程 ​

使用工作階段的驗證流程可能會有所不同,取決於使用者在您的應用程式中如何進行驗證。讓我們看看它在表單型驗證中的運作方式:

  1. 用戶端向伺服器發送包含 Web 表單資料(包括使用者名稱與密碼)的請求。
  2. 伺服器驗證用戶端傳送的憑據,將使用者名稱儲存到 Cookie 工作階段中,並回傳請求的內容以及包含使用者名稱的 Cookie。
  3. 用戶端攜帶 Cookie 對受保護的資源發送後續請求。
  4. 根據接收到的 Cookie 資料,Ktor 會檢查該使用者是否存在 Cookie 工作階段,並可選擇對接收到的工作階段資料執行額外驗證。在驗證成功的情況下,伺服器會回傳請求的內容。

安裝工作階段驗證 ​

若要安裝 session 驗證提供者,請在 install 區塊中以所需的工作階段型別呼叫 session 函式:

kotlin
import io.ktor.server.application.*
import io.ktor.server.auth.*
import io.ktor.server.sessions.*
//...
install(Authentication) {
    session<UserSession> {
        // 設定工作階段驗證
    }
}

設定工作階段驗證 ​

本節示範如何透過表單型驗證對使用者進行驗證、將該使用者的資訊儲存到 Cookie 工作階段中,然後在後續請求中使用 session 提供者授權此使用者。

如需完整範例,請參閱 auth-form-session。

步驟 1:建立資料類別 ​

首先,您需要建立一個用於儲存工作階段資料的資料類別:

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

步驟 2:安裝並設定工作階段 ​

建立資料類別後,您需要安裝並設定 Sessions 外掛程式。以下範例安裝並設定具有指定 Cookie 路徑與過期時間的 Cookie 工作階段。

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

若要進一步了解如何設定工作階段,請參閱工作階段設定概觀。

步驟 3:設定工作階段驗證 ​

session 驗證提供者透過 SessionAuthenticationProvider.Config 類別公開其設定。在以下範例中,指定了以下設定:

  • validate() 函式會檢查工作階段執行個體,並在驗證成功的情況下傳回型別為 Any 的 principal。
  • challenge() 函式指定了驗證失敗時執行的操作。例如,您可以重新導向回登入頁面或傳送 UnauthorizedResponse。
kotlin
install(Authentication) {
    session<UserSession>("auth-session") {
        validate { session ->
            if(session.name.startsWith("jet")) {
                session
            } else {
                null
            }
        }
        challenge {
            call.respondRedirect("/login")
        }
    }
}

步驟 4:將使用者資料儲存於工作階段中 ​

若要將已登入使用者的資訊儲存到工作階段,請使用 call.sessions.set() 函式。

以下範例展示了使用 Web 表單的簡單驗證流程:

kotlin
authenticate("auth-form") {
    post("/login") {
        val principal =
            call.principal<UserIdPrincipal>()
        val userName = principal?.name.toString()
        val session = UserSession(
            name = userName,
            count = 1
        )
        call.sessions.set(session)
        call.respondRedirect("/hello")
    }
}

有關表單型驗證流程的詳細資訊,請參閱表單型驗證文件。

步驟 5:保護特定資源 ​

設定好 session 提供者後,您可以使用 authenticate() 函式來保護應用程式中的特定資源。

驗證成功後,您可以在路由處理常式中使用 call.principal() 函式來擷取已驗證的 principal(在此例中為 UserSession 執行個體):

kotlin
authenticate("auth-session") {
    get("/hello") {
        val userSession = call.principal<UserSession>()
        val next = userSession?.copy(
            count = userSession.count + 1
        )
        call.sessions.set(next)
        call.respondText(
            "Hello, ${userSession?.name}! " +
                "Visit count is ${userSession?.count}."
        )
    }
}

如需完整範例,請參閱 auth-form-session。